Organizations and projects
In the API, an organization is a tenant. A standalone install has one, with the id default. These endpoints need a Keycloak access token. See Users, roles and projects for how the roles work.
Members are identified by their Keycloak user ID, the sub claim of their token.
Projects
/projectsThe projects you can see: those you are a member of, and every project under an organization or folder you are an admin of. A platform admin sees all of them.
Query parameters
tenant_idstringoptional/projectsCreates a project. Needs the admin role on the organization, or on the folder you create it in.
Body
idstringrequirednamestringrequireddescriptionstringoptionaltenant_idstringoptionaldefault.folder_idstringoptionalResponses
Project members
/projects/{project_id}/membersThe project's members, with user_sub, username and role. Needs any role on the project.
/projects/{project_id}/membersAdds a member or changes their role. Needs the admin role on the project.
Body
user_substringrequiredusernamestringrequiredrolestringrequiredviewer, developer or admin./projects/{project_id}/members/{user_sub}Removes a member. Needs the admin role on the project.
Folders
/tenants/{tenant_id}/foldersEvery folder in an organization, as a flat list with id, name, description, parent_folder_id and depth. Needs a role on the organization or on a folder in it. A platform admin can list any organization's folders. Anyone else gets 403.
/tenants/{tenant_id}/foldersCreates a folder. Needs the admin role on the organization, or on the parent folder. Folders nest up to 10 levels deep.
Body
idstringrequirednamestringrequireddescriptionstringoptionalparent_folder_idstringoptional/folders/{folder_id}/members/folders/{folder_id}/members/folders/{folder_id}/members/{user_sub}Folder members, with the same body as project members. Changing them needs the admin role on the folder or above it.
Organizations
/tenantsThe organizations you are a member of. A platform admin sees all of them.
/tenants/{tenant_id}/members/tenants/{tenant_id}/members/tenants/{tenant_id}/members/{user_sub}Organization members, with the same body as project members. Changing them needs the admin role on the organization.
/tenantsA standalone install already has its one organization, so this returns 409.
Delete and restore a project
| Method and path | Who | What it does |
|---|---|---|
DELETE /projects/{project_id}?confirm=<project id> | organization or folder admin, or platform admin | Deletes the project at once: it disappears from every route, its project and agent keys are revoked, and its channels and hosted chats are switched off. Refused with 409 while it still runs a code agent, a build or a model deployment. |
GET /projects/deleted | the same | Deleted projects you could restore, with when each will be purged. |
POST /projects/{project_id}/restore | the same | Bring it back, until the purge starts. Revoked keys stay revoked and switched-off chats and channels stay off. |
POST /projects/{project_id}/purge | platform admin | Purge at the next sweep instead of waiting. |
A deleted project is purged after projects.purgeAfterHours, 7 days by default. See Delete a project.
Find people
Member routes take a Keycloak user ID (sub). To find one by name or email, use GET /directory/users?q=. People can also get memberships through groups.