> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt > Use this file to discover all available pages before exploring further. # Add a team to a realm > Adds a team to the realm's team list and installs it on the realm's online daemons, with the organization's and realm's agent settings. Daemons that come online later get it too. The team is added to the realm's organization first when you may do that. Requires a realm operator (or higher) with the `realms.teams.manage` permission on the realm that owns the realm given by `realm_id`. ## OpenAPI ````yaml /openapi/hub-by-tag/hub-realms.yaml post /v1/realms/add_team openapi: 3.0.3 info: title: 'CliqHub API: Realms' version: 1.0.0 description: >- A realm groups daemons, the people who may use them, and the teams they should run. Its members have a role: member (can see), operator (can run and operate) or admin (can manage). Daemons join with a realm token, people with an invitation. A realm's **team list** is the set of teams its daemons should have: Add a team to a realm installs it on the realm's online daemons, and daemons that join later get it too. A realm can also have its own notification rules, and A2A access so outside agents can send it tasks. Several of these endpoints answer `{ ok: true, realm }`-style bodies rather than `{ ok: true, data }`; each page shows its exact shape. servers: - url: https://{host} variables: host: default: cliqhub.io description: CliqHub host security: [] tags: - name: Realms description: >- A realm groups daemons, the people who may use them, and the teams they should run. Its members have a role: member (can see), operator (can run and operate) or admin (can manage). Daemons join with a realm token, people with an invitation. A realm's **team list** is the set of teams its daemons should have: Add a team to a realm installs it on the realm's online daemons, and daemons that join later get it too. A realm can also have its own notification rules, and A2A access so outside agents can send it tasks. Several of these endpoints answer `{ ok: true, realm }`-style bodies rather than `{ ok: true, data }`; each page shows its exact shape. paths: /v1/realms/add_team: post: tags: - Realms summary: Add a team to a realm description: >- Adds a team to the realm's team list and installs it on the realm's online daemons, with the organization's and realm's agent settings. Daemons that come online later get it too. The team is added to the realm's organization first when you may do that. Requires a realm operator (or higher) with the `realms.teams.manage` permission on the realm that owns the realm given by `realm_id`. operationId: POST_v1_realms_add_team requestBody: required: true content: application/json: schema: type: object properties: realm_id: type: string minLength: 1 description: Realm UUID scope: type: string minLength: 1 description: Team scope (e.g. cliq or org slug) slug: type: string minLength: 1 description: Team slug required: - realm_id - scope - slug examples: default: value: realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b scope: acme slug: code-review responses: '200': description: Success. content: application/json: schema: type: object required: - ok - team_list - install properties: ok: type: boolean enum: - true description: Always `true` on success. team_list: type: array description: The realm's team list after the change. items: $ref: '#/components/schemas/TeamRef' install: type: object description: How each online daemon answered the install. properties: scope: type: string slug: type: string daemon_results: type: array items: $ref: '#/components/schemas/TeamDaemonResult' example: ok: true team_list: - scope: acme slug: code-review install: scope: acme slug: code-review daemon_results: - daemon_id: 7d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d ok: true '401': description: >- `unauthorized`: No `Authorization` header, or the token is malformed, expired or revoked. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: unauthorized: summary: unauthorized value: ok: false error: code: unauthorized message: Authentication required '403': description: >- `forbidden`: You can see the record but your role in its realm is too low or lacks the required permission. `team_not_in_org`: The team is not in the realm's organization and you may not add teams to the organization. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: forbidden: summary: forbidden value: ok: false error: code: forbidden message: You do not have access to do this team_not_in_org: summary: team_not_in_org value: ok: false error: >- @acme/code-review isn't in this org yet. Ask someone who can add teams to the org to add it first. code: team_not_in_org '404': description: >- `not_found`: The realm does not exist or is in a realm you cannot see (404 rather than 403, so its existence is not revealed). `not_found`: The realm does not exist. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: not_found: summary: not_found value: ok: false error: code: not_found message: Not found not_found (endpoint): summary: not_found (endpoint) value: ok: false error: Realm not found code: not_found '422': description: >- `invalid_params`: The body fails the request schema: a required field is missing or a value has the wrong type or format. The message lists every issue as `field: problem`. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: invalid_params: summary: invalid_params value: ok: false error: 'realm_id: Required' code: invalid_params '500': description: >- `internal_error`: An unexpected server fault. Retry later; if it persists, report it with the time of the request. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: internal_error: summary: internal_error value: ok: false error: Internal server error code: internal_error security: - BearerAuth: [] components: schemas: TeamRef: type: object required: - scope - slug properties: scope: type: string example: acme slug: type: string example: code-review TeamDaemonResult: type: object required: - daemon_id - ok properties: daemon_id: type: string ok: type: boolean description: The daemon accepted the command. already_installed: type: boolean description: Install only. The version was already there. error: type: string description: Why it failed, when `ok` is false. HubErr: type: object required: - ok - error description: >- Every failure. Route-policy denials (401/403/404, and 400 when neither realm_id nor org_id was sent) answer `error` as `{ code, message }`; errors raised by the endpoint answer `error` as the message with the code beside it in `code`. Every error has a code. See [Errors](/hub-api/errors). properties: ok: type: boolean description: Always false on error error: description: The message, or `{ code, message }` for an access denial. oneOf: - type: string - type: object required: - code - message properties: code: type: string message: type: string code: type: string description: Stable error code of an endpoint error. details: type: object additionalProperties: true description: Structured detail, when there is some. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: cliq_tok_* | cliq_dt_* description: >- User PAT (`cliq_tok_…`, including session-scoped) or realm token (`cliq_dt_…`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.