Teams API — List and Create Teams in Your Hierarchy

The Teams API lets you inspect the team tree associated with your API key and provision new teams beneath it. Every API key is bound to a root team — all read and write operations are scoped to that root and its descendants. You can use this API to mirror your institution’s organizational structure (campuses, departments, cohorts) inside Examino.

List Teams

string

required

Bearer token. Format: Bearer $EXAMINO_API_KEY

Required scope: teams:read

Returns your key’s root team and every descendant team, regardless of nesting depth.

Request

curl https://app.examino.ai/api/v1/teams \
  -H "Authorization: Bearer $EXAMINO_API_KEY"

Response

{
  "rootTeamId": "6b0b1f1a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "items": [
    {
      "id": "6b0b1f1a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "Groupe Exemple",
      "slug": "groupe-exemple",
      "kind": "workspace",
      "parentTeamId": null,
      "createdAt": "2026-01-12T09:31:04.221Z"
    },
    {
      "id": "d4e5f6a7-b8c9-40d1-a2b3-c4d5e6f7a8b9",
      "name": "Campus Lyon",
      "slug": "campus-lyon",
      "kind": "workspace",
      "parentTeamId": "6b0b1f1a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
      "createdAt": "2026-02-03T14:02:57.880Z"
    }
  ],
  "total": 2
}

Response Fields

string

The UUID of the team the API key is bound to. Every other item in items is a direct or indirect descendant of this team.

array

Flat list of all teams in scope — the root team plus all descendants.

Show items[]

string

UUID of the team.

string

Human-readable display name of the team.

string

URL-safe identifier derived from the team name. Used in Examino dashboard URLs.

string

Team type. workspace teams can hold exams and be assigned credits. folder teams are purely organizational nodes and cannot hold exams directly.

string | null

UUID of this team’s parent, or null if this is the root team.

string

ISO 8601 timestamp recording when the team was created.

integer

Total number of teams returned in items.

Create a Team

string

required

Bearer token. Format: Bearer $EXAMINO_API_KEY

string

required

Must be application/json.

Required scope: teams:write

Creates a new team as a child of an existing team within your key’s scope. On success, returns the newly created team object with HTTP 201 Created.

Request Parameters

string

required

Display name for the new team. Must be between 1 and 120 characters.

string

UUID of the team that will become the parent. Must belong to your key’s scope. Defaults to your key’s root team if omitted.

string

default:"workspace"

Team type. Pass workspace for teams that will hold exams, or folder for purely organizational grouping nodes. Defaults to workspace.

Request

curl -X POST https://app.examino.ai/api/v1/teams \
  -H "Authorization: Bearer $EXAMINO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campus Lille",
    "parentTeamId": "6b0b1f1a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
    "kind": "workspace"
  }'

Response

{
  "id": "0a1b2c3d-4e5f-4061-8273-84950a1b2c3d",
  "name": "Campus Lille",
  "slug": "campus-lille",
  "kind": "workspace",
  "parentTeamId": "6b0b1f1a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "createdAt": "2026-09-17T08:14:22.019Z"
}

Response Fields

string

UUID assigned to the newly created team.

string

Display name as provided in the request.

string

Auto-generated URL-safe identifier derived from name.

string

workspace or folder, as specified in the request (or the default).

string

UUID of the parent team. Matches the value you provided, or your key’s root team if you omitted parentTeamId.

string

ISO 8601 timestamp of when the team was created.

Error Responses

404 — Parent team not found

The parentTeamId you provided either does not exist or is outside your API key’s scope. Verify that the UUID belongs to a team within your key’s hierarchy.

{
  "error": "not_found",
  "message": "parentTeamId not found within key scope"
}

400 — Invalid request

The request body is malformed or the specified parent would create an impossible hierarchy (for example, making a team its own ancestor). Check your payload and team relationships before retrying.

{
  "error": "invalid_request",
  "message": "The specified parent would create a circular hierarchy"
}

409 — Name conflict

A team with the same name already exists under the same parent. Team names must be unique at each level of the hierarchy.

{
  "error": "conflict",
  "message": "A team with this name already exists under the specified parent"
}

Slugs are derived automatically from the team name at creation time. If you later rename a team through the dashboard, the slug does not change — existing integrations using the slug remain stable.

Teams & Credits

Exams

Teams API — List and Create Teams in Your Hierarchy

List Teams

Request

Response

Response Fields

Create a Team

Request Parameters

Request

Response

Response Fields

Error Responses

​List Teams

​Request

​Response

​Response Fields

​Create a Team

​Request Parameters

​Request

​Response

​Response Fields

​Error Responses

List Teams

Request

Response

Response Fields

Create a Team

Request Parameters

Request

Response

Response Fields

Error Responses