# Share folder (/docs/api/folders/share-folder)

## OpenAPI

```json
{
  "info": {
    "description": "The Circleback public REST API provides programmatic access to your meetings, notes, action items, transcripts, and more. Authenticate every request by sending your API key as a bearer token.",
    "title": "Circleback Public API",
    "version": "1.0.0"
  },
  "openapi": "3.2.0",
  "servers": [
    {
      "url": "https://circleback.ai/api"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "bearerFormat": "cb_<secret>",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "tags": [
    {
      "description": "See the folders that organize meetings, who can read them, and the rules that file meetings into them.",
      "name": "Folders"
    }
  ],
  "paths": {
    "/folder/{folderId}/share": {
      "post": {
        "description": "Shares a folder with people, teams, or workspaces, changes their access, or removes them. People outside the folder's workspace, even without an account, can be added by email. On the workspace folder, only a workspace's access can change. Returns the updated folder.",
        "parameters": [
          {
            "description": "The unique identifier of the folder.",
            "in": "path",
            "name": "folderId",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "description": "The people, teams or workspaces to share with, up to 50. Targets that fail are listed in errors; the rest still apply.",
                "items": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "access": {
                          "anyOf": [
                            {
                              "description": "The access level to grant.",
                              "enum": [
                                "Editor",
                                "Viewer",
                                "LimitedViewer"
                              ],
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The access they get to the folder's meetings, or null for none. New grants get Editor."
                        },
                        "email": {
                          "format": "email",
                          "type": "string"
                        },
                        "isContributor": {
                          "description": "Whether the folder's rules file their matching meetings. People in the folder's workspace can add their meetings by hand either way; people outside it need this. New grants don't contribute.",
                          "type": "boolean"
                        },
                        "isOwner": {
                          "description": "Whether they own the folder. Only people in its workspace can.",
                          "type": "boolean"
                        },
                        "remove": {
                          "const": true,
                          "description": "Removes them from the folder. Other fields are ignored.",
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "email"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "profileId": {
                          "exclusiveMinimum": 0,
                          "type": "integer"
                        },
                        "access": {
                          "anyOf": [
                            {
                              "description": "The access level to grant.",
                              "enum": [
                                "Editor",
                                "Viewer",
                                "LimitedViewer"
                              ],
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The access they get to the folder's meetings, or null for none. New grants get Editor."
                        },
                        "isContributor": {
                          "description": "Whether the folder's rules file their matching meetings. People in the folder's workspace can add their meetings by hand either way; people outside it need this. New grants don't contribute.",
                          "type": "boolean"
                        },
                        "isOwner": {
                          "description": "Whether they own the folder. Only people in its workspace can.",
                          "type": "boolean"
                        },
                        "remove": {
                          "const": true,
                          "description": "Removes them from the folder. Other fields are ignored.",
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "profileId"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "access": {
                          "anyOf": [
                            {
                              "description": "The access level to grant.",
                              "enum": [
                                "Editor",
                                "Viewer",
                                "LimitedViewer"
                              ],
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The access they get to the folder's meetings, or null for none. New grants get Editor."
                        },
                        "isContributor": {
                          "description": "Whether the folder's rules file their matching meetings. People in the folder's workspace can add their meetings by hand either way; people outside it need this. New grants don't contribute.",
                          "type": "boolean"
                        },
                        "remove": {
                          "const": true,
                          "description": "Removes them from the folder. Other fields are ignored.",
                          "type": "boolean"
                        },
                        "teamId": {
                          "exclusiveMinimum": 0,
                          "type": "integer"
                        }
                      },
                      "required": [
                        "teamId"
                      ],
                      "type": "object"
                    },
                    {
                      "additionalProperties": false,
                      "properties": {
                        "access": {
                          "anyOf": [
                            {
                              "description": "The access level to grant.",
                              "enum": [
                                "Editor",
                                "Viewer",
                                "LimitedViewer"
                              ],
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The access they get to the folder's meetings, or null for none. New grants get Editor."
                        },
                        "isContributor": {
                          "description": "Whether the folder's rules file their matching meetings. People in the folder's workspace can add their meetings by hand either way; people outside it need this. New grants don't contribute.",
                          "type": "boolean"
                        },
                        "remove": {
                          "const": true,
                          "description": "Removes them from the folder. Other fields are ignored.",
                          "type": "boolean"
                        },
                        "workspaceId": {
                          "exclusiveMinimum": 0,
                          "type": "integer"
                        }
                      },
                      "required": [
                        "workspaceId"
                      ],
                      "type": "object"
                    }
                  ]
                },
                "maxItems": 50,
                "minItems": 1,
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "description": "The unique identifier of the folder.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "name": {
                      "description": "The display name of the folder.",
                      "type": "string"
                    },
                    "url": {
                      "description": "The link to the folder in Circleback.",
                      "type": "string"
                    },
                    "canManage": {
                      "description": "Whether you can change the folder, its rules, and its members.",
                      "type": "boolean"
                    },
                    "color": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The color of the folder icon, or null for the default."
                    },
                    "icon": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The icon shown for the folder."
                    },
                    "visibility": {
                      "anyOf": [
                        {
                          "enum": [
                            "Closed",
                            "Private"
                          ],
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Who can find the folder. Closed folders are listed to everyone in the workspace, and Private folders only to their members and workspace admins. Null for Default folders."
                    },
                    "workspaceId": {
                      "description": "The unique identifier of the workspace the folder belongs to.",
                      "exclusiveMinimum": 0,
                      "type": "number"
                    },
                    "errors": {
                      "description": "Targets that could not be shared. Omitted when all succeed.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "error": {
                            "description": "Why the target could not be shared.",
                            "type": "string"
                          },
                          "index": {
                            "description": "The position of the target in the request.",
                            "type": "number"
                          }
                        },
                        "required": [
                          "index",
                          "error"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "invitations": {
                      "description": "People invited to add their meetings who have not accepted yet, with the access accepting gives them. Only listed to people who manage the folder.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "profileId": {
                            "description": "The unique identifier of their profile.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The name of the user."
                          },
                          "access": {
                            "anyOf": [
                              {
                                "enum": [
                                  "Owner",
                                  "Editor",
                                  "Viewer",
                                  "LimitedViewer"
                                ],
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The access they get to the folder's meetings, or null when they can't read them."
                          },
                          "email": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The email address of the user."
                          }
                        },
                        "required": [
                          "name",
                          "email",
                          "access",
                          "profileId"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "invitedPeople": {
                      "description": "People without an account who were added by email, with the access they get when they sign up. Only listed to people who manage the folder.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "profileId": {
                            "description": "The unique identifier of their profile.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          },
                          "access": {
                            "anyOf": [
                              {
                                "enum": [
                                  "Owner",
                                  "Editor",
                                  "Viewer",
                                  "LimitedViewer"
                                ],
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The access they get to the folder's meetings, or null when they can't read them."
                          },
                          "email": {
                            "description": "The email address they were invited at.",
                            "type": "string"
                          },
                          "isContributor": {
                            "description": "Whether the folder's rules file their matching meetings, for people in the folder's workspace. People outside it need this to add their meetings by hand; people inside can add theirs either way.",
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "profileId",
                          "email",
                          "access",
                          "isContributor"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "joinRequests": {
                      "description": "People who asked to join the folder. Only listed to people who manage the folder.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "profileId": {
                            "description": "The unique identifier of their profile.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The name of the user."
                          },
                          "email": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The email address of the user."
                          }
                        },
                        "required": [
                          "profileId",
                          "name",
                          "email"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "members": {
                      "description": "The people who can read or add to the folder.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "profileId": {
                            "description": "The unique identifier of the member profile.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The name of the user."
                          },
                          "access": {
                            "anyOf": [
                              {
                                "enum": [
                                  "Owner",
                                  "Editor",
                                  "Viewer",
                                  "LimitedViewer"
                                ],
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The access they get to the folder's meetings, or null when they can't read them."
                          },
                          "email": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The email address of the user."
                          },
                          "isContributor": {
                            "description": "Whether the folder's rules file their matching meetings, for people in the folder's workspace. People outside it need this to add their meetings by hand; people inside can add theirs either way.",
                            "type": "boolean"
                          },
                          "isOwner": {
                            "description": "Whether they own the folder and can manage it.",
                            "type": "boolean"
                          },
                          "userId": {
                            "description": "The unique identifier of the user.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          },
                          "teamIds": {
                            "description": "The teams that give the member access.",
                            "items": {
                              "exclusiveMinimum": 0,
                              "type": "number"
                            },
                            "type": "array"
                          },
                          "workspaceIds": {
                            "description": "The workspaces that give the member access.",
                            "items": {
                              "exclusiveMinimum": 0,
                              "type": "number"
                            },
                            "type": "array"
                          }
                        },
                        "required": [
                          "userId",
                          "name",
                          "email",
                          "access",
                          "profileId",
                          "isContributor",
                          "isOwner",
                          "teamIds",
                          "workspaceIds"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "ruleGroups": {
                      "description": "The rules that file new meetings into the folder. A meeting matches when any group matches, and a group matches when all its conditions do.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "conditions": {
                            "items": {
                              "additionalProperties": false,
                              "properties": {
                                "operator": {
                                  "description": "Each type allows only some operators.",
                                  "enum": [
                                    "Include",
                                    "DoNotInclude",
                                    "AreAll",
                                    "AreNotAll",
                                    "Is",
                                    "IsNot",
                                    "Contains",
                                    "DoesNotContain",
                                    "GreaterThan",
                                    "LessThan"
                                  ],
                                  "type": "string"
                                },
                                "type": {
                                  "enum": [
                                    "Tags",
                                    "MeetingName",
                                    "Participants",
                                    "InviteeEmails",
                                    "InviteeEmailDomains",
                                    "NumberOfInvitees",
                                    "EveryMeeting"
                                  ],
                                  "type": "string"
                                },
                                "value": {
                                  "description": "For Tags, a tag ID.",
                                  "minLength": 1,
                                  "type": "string"
                                }
                              },
                              "required": [
                                "type",
                                "operator",
                                "value"
                              ],
                              "type": "object"
                            },
                            "minItems": 1,
                            "type": "array"
                          }
                        },
                        "required": [
                          "conditions"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "teams": {
                      "description": "The teams that can read or add to the folder.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "access": {
                            "anyOf": [
                              {
                                "enum": [
                                  "Owner",
                                  "Editor",
                                  "Viewer",
                                  "LimitedViewer"
                                ],
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The access they get to the folder's meetings, or null when they can't read them."
                          },
                          "isContributor": {
                            "description": "Whether the folder's rules file their matching meetings, for people in the folder's workspace. People outside it need this to add their meetings by hand; people inside can add theirs either way.",
                            "type": "boolean"
                          },
                          "teamId": {
                            "description": "The unique identifier of the team.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          }
                        },
                        "required": [
                          "teamId",
                          "access",
                          "isContributor"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "type": {
                      "description": "The kind of folder. A Default folder catches the workspace's meetings that no other folder does. The PersonalPrivate folder is your Private folder, with the ID private, and holds your meetings that are in no folder. Shared folders are made by people in the workspace.",
                      "enum": [
                        "Default",
                        "PersonalPrivate",
                        "Shared"
                      ],
                      "type": "string"
                    },
                    "workspaces": {
                      "description": "The workspaces whose active members can read or add to the folder.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "access": {
                            "anyOf": [
                              {
                                "enum": [
                                  "Owner",
                                  "Editor",
                                  "Viewer",
                                  "LimitedViewer"
                                ],
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The access they get to the folder's meetings, or null when they can't read them."
                          },
                          "isContributor": {
                            "description": "Whether the folder's rules file their matching meetings, for people in the folder's workspace. People outside it need this to add their meetings by hand; people inside can add theirs either way.",
                            "type": "boolean"
                          },
                          "workspaceId": {
                            "description": "The unique identifier of the workspace.",
                            "exclusiveMinimum": 0,
                            "type": "number"
                          }
                        },
                        "required": [
                          "workspaceId",
                          "access",
                          "isContributor"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "icon",
                    "color",
                    "type",
                    "visibility",
                    "workspaceId",
                    "url",
                    "canManage",
                    "members",
                    "invitations",
                    "joinRequests",
                    "invitedPeople",
                    "ruleGroups",
                    "teams",
                    "workspaces"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Successful response."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "code": {
                      "description": "A machine-readable code identifying the type of failure.",
                      "type": "string"
                    },
                    "error": {
                      "description": "A human-readable message explaining why the request failed.",
                      "type": "string"
                    },
                    "seatsToAdd": {
                      "description": "The authoritative number of workspace seats required.",
                      "exclusiveMinimum": 0,
                      "type": "integer"
                    },
                    "issues": {
                      "description": "The field-level validation issues found in an invalid request.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "message": {
                            "description": "A human-readable explanation of the validation failure.",
                            "type": "string"
                          },
                          "path": {
                            "description": "The location of the request field that failed validation.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "path",
                          "message"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The request failed validation."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1folder~1{folderId}~1share/post/responses/400/content/application~1json/schema"
                }
              }
            },
            "description": "The request exceeded the rate limit for the account's plan, which the error message names: 3 requests per second and 20 per minute on Free, 20 per second and 300 per minute on Pro, Business, and Enterprise. Retry after the number of seconds in the `Retry-After` header."
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Share folder",
        "tags": [
          "Folders"
        ]
      }
    }
  }
}
```