Teams and users API
Create and update Cortex teams and users, assign people to teams created in the Portal, and review bulk directory changes before applying them.
Use the Cortex organization directory API to manage teams and users. If your teams and users already exist in Cortex Portal, look up their IDs and assign memberships directly. You do not need to recreate either.
Authentication and permissions
Send a valid Cortex session access token as Authorization: Bearer <token>. Gateway inference keys are not accepted by this API. Use the Cortex API origin for your deployment, not the docs URL. If you need the API origin or are planning an unattended integration, contact Chaos Labs to confirm the setup for your organization.
Set CORTEX_API_ORIGIN to the API origin (without a trailing slash) and CORTEX_SESSION_TOKEN to your session token. Keep the token out of scripts and logs. Set ORG_ID to your organization's org_id, available in the organizations array from GET /ai/memory/admin/organizations.
Directory reads are available to authenticated members of the organization. Use an organization Admin for user writes, bulk imports, and organization-wide team changes. An assigned Team Manager can edit teams and manage memberships within their assigned team and its descendants, and create child teams there. Assigning team managers or deleting teams requires an Admin. A Team Manager moving a person's primary team must manage both the previous and new primary teams.
ORG_API="${CORTEX_API_ORIGIN}/ai/memory/admin/organizations/${ORG_ID}"Teams and memberships
Paths below are relative to ORG_API. Send Content-Type: application/json with JSON request bodies.
| Method and path | Result |
|---|---|
GET /teams | 200, with a teams array. Each team includes team_id, name, parent_team_id, manager_user_id, and direct and subtree member counts. |
POST /teams | 201, with the new team. Send name (1 to 200 characters) and optionally parent_team_id and manager_user_id. Example: {"name":"Engineering"}. |
PATCH /teams/{team_id} | 200, with the updated team. Send only the fields to change. Use null for parent_team_id to make a team top-level, or for manager_user_id to clear the manager. |
GET /teams/{team_id}/members | 200, with direct members only, not members of child teams. Supports search, limit (1 to 100, default 50), and offset (default 0). Returns users, total, limit, and offset. |
PUT /teams/{team_id}/members/{user_id} | 204, with no body. Adds a membership or makes it primary. Send {"is_primary":false} to add without replacing an existing primary team. |
DELETE /teams/{team_id}/members/{user_id} | 204, with no body. Removes the direct membership. If it was primary and other memberships remain, Cortex promotes one of them. |
Use PATCH, not PUT, to update team details. Membership writes take one user and one team per request.
Users
| Method and path | Result |
|---|---|
GET /users | 200, with users, total, limit, and offset. Each user includes user_id, email, and their teams. |
GET /users/{user_id} | 200, with the matching user. |
POST /users | 201, with the new user. For a person, send a work email from a domain managed by your organization. role defaults to member. Example: {"email":"alex@example.com","display_name":"Alex Rivera"}. Assign team memberships separately. |
PATCH /users/{user_id} | 200, with the updated user. Send only the fields to change, for example {"title":"Engineering Lead"}. |
PUT /users/{user_id} | 200, with the updated user. Requires all replacement fields listed below. |
DELETE /users/{user_id} | 204, with no body. Deactivates the user rather than deleting their record or history. To reactivate a user, send PATCH with {"status":"active"}. Devices must be enrolled again. |
For PUT, send role, visibility, status, is_protected, can_view_protected, manager_user_id, title, display_name, and plans. Only manager_user_id, title, and display_name accept null to clear the field. Prefer PATCH to change a single field without overwriting access or plan settings. Neither operation changes team memberships.
For large directories, pass limit=100 and start with offset=0. Advance the offset by the number of users returned until you reach total or receive an empty page. Use search for a case-insensitive substring match on name or email, kind=person to exclude service accounts, and status=active for active users. Use unassigned=true to find users with no teams, or team_id to filter by direct membership. To include child teams, combine team_id with include_descendants=true. Do not combine unassigned=true with team_id.
Assign people to teams created in Cortex Portal
- List teams with
GET /teamsand take theteam_idof each intended team. Checkparent_team_idif you need to distinguish teams by their position in the hierarchy. - List users with
GET /users. If you search by work email, check for an exact email match in the results before using itsuser_id. For a roster, build an email-to-ID mapping from the paginated directory. - Send one membership request per user-team pair. For example, after setting
TEAM_IDandUSER_IDto the IDs you looked up:
curl --fail-with-body --silent --show-error \
--request PUT "$ORG_API/teams/$TEAM_ID/members/$USER_ID" \
--header "Authorization: Bearer $CORTEX_SESSION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"is_primary":false}'A person's first team becomes primary even if you send is_primary: false. Send true to make the target team primary without removing other memberships. Sending false never demotes an existing primary. You can repeat the same request without creating a duplicate membership.
For a roster, record success or failure per pair and verify with GET /teams/{team_id}/members or GET /users/{user_id}. The individual requests are independent: a failed request does not roll back earlier assignments.
Apply a roster in bulk
Use a directory import when your roster specifies the complete team membership for each person. team_names replaces that person's team memberships, rather than adding to them. Include every team they should keep, or omit team_names to leave memberships unchanged. Use the team names from GET /teams. A new name can create a team and a new email can create a user, so check the roster for typos before applying. Use individual membership PUT requests if you only want to add memberships.
- Send
POST /directory-importswith a JSON body like the one below. The API accepts up to 5,000 rows and 20,000 total team assignments per import. Staging returns201with asnapshot_id, asummary, and row validation results. It does not change the directory.
{
"source_kind": "csv",
"rows": [
{
"email": "alex@example.com",
"team_names": ["Engineering", "Platform"],
"primary_team_name": "Platform"
}
]
}- Review each row's
validation_statusandplanned_action. To retrieve the review again, useGET /directory-imports/{snapshot_id}. Correct unexpected creates or validation errors and stage a fresh snapshot. If you omitprimary_team_nameon a nonempty team list, the first team becomes primary. - Send
POST /directory-imports/{snapshot_id}/applywith no body. Cortex applies eligible rows in one transaction and returns200with the snapshot status and counts forcreated,updated, andskipped. People not in the roster are unchanged. If the directory changed after staging and the API returns a revision conflict, stage and review a new snapshot. If the apply response is lost, check the snapshot status before submitting another import.
Common errors
401: Check that the Cortex session token is valid and has not expired.403: Check your role and, for Team Managers, which teams you manage.404: Check that the organization, team, or user ID is correct and in scope.409: Inspect the response for a conflict, such as a duplicate user email or a stale import snapshot.422: Check the request fields and query parameters. A userPUTrequires all replacement fields, whilePATCHrequires at least one field.
See Roles and visibility for how team membership affects what people can see in Cortex Portal.