Skip to main content

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​

GET/projects

The 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
Only projects in this organization.
POST/projects

Creates a project. Needs the admin role on the organization, or on the folder you create it in.

Body​

idstringrequired
The project's slug.
namestringrequired
Its display name.
descriptionstringoptional
What it is for.
tenant_idstringoptional
The organization. Default default.
folder_idstringoptional
The folder to put it in.

Responses​

200
Created.
400
The folder is not in this organization.
403
You are not an admin of the organization or folder.
404
No such organization.
409
A project with this id exists.

Project members​

GET/projects/{project_id}/members

The project's members, with user_sub, username and role. Needs any role on the project.

POST/projects/{project_id}/members

Adds a member or changes their role. Needs the admin role on the project.

Body​

user_substringrequired
The person's Keycloak user ID.
usernamestringrequired
Their username, for display.
rolestringrequired
viewer, developer or admin.
DELETE/projects/{project_id}/members/{user_sub}

Removes a member. Needs the admin role on the project.

Folders​

GET/tenants/{tenant_id}/folders

Every 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.

POST/tenants/{tenant_id}/folders

Creates a folder. Needs the admin role on the organization, or on the parent folder. Folders nest up to 10 levels deep.

Body​

idstringrequired
The folder's slug.
namestringrequired
Its display name.
descriptionstringoptional
What it holds.
parent_folder_idstringoptional
The folder to put it in. Leave it out for a top-level folder.
GET/folders/{folder_id}/members
POST/folders/{folder_id}/members
DELETE/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​

GET/tenants

The organizations you are a member of. A platform admin sees all of them.

GET/tenants/{tenant_id}/members
POST/tenants/{tenant_id}/members
DELETE/tenants/{tenant_id}/members/{user_sub}

Organization members, with the same body as project members. Changing them needs the admin role on the organization.

POST/tenants

A standalone install already has its one organization, so this returns 409.

Delete and restore a project​

Method and pathWhoWhat it does
DELETE /projects/{project_id}?confirm=<project id>organization or folder admin, or platform adminDeletes 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/deletedthe sameDeleted projects you could restore, with when each will be purged.
POST /projects/{project_id}/restorethe sameBring it back, until the purge starts. Revoked keys stay revoked and switched-off chats and channels stay off.
POST /projects/{project_id}/purgeplatform adminPurge 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.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →