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

# Create a realm

> Creates a realm in an organization. You become its admin. The slug must be unique in the organization.

Requires a role with the `realms.create` permission in the organization given by `org_id`.



## OpenAPI

````yaml /openapi/hub-by-tag/hub-realms.yaml post /v1/realms/create
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/create:
    post:
      tags:
        - Realms
      summary: Create a realm
      description: >-
        Creates a realm in an organization. You become its admin. The slug must
        be unique in the organization.


        Requires a role with the `realms.create` permission in the organization
        given by `org_id`.
      operationId: POST_v1_realms_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                  description: >-
                    Organization this call targets. Required on create; optional
                    filter on get;
                slug:
                  type: string
                  minLength: 1
                  description: URL-safe realm slug unique within the org
                name:
                  type: string
                  minLength: 1
                  description: Display name
              required:
                - org_id
                - slug
                - name
            examples:
              default:
                value:
                  org_id: 2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f
                  slug: production
                  name: Production
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - realm
                properties:
                  ok:
                    type: boolean
                    enum:
                      - true
                    description: Always `true` on success.
                  realm:
                    $ref: '#/components/schemas/RealmData'
              example:
                ok: true
                realm:
                  id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b
                  slug: production
                  org_slug: acme
                  qualified_slug: acme.production
                  name: Production
                  owner_user_id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  created_by: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  created_by_username: sshah
                  created_at: 1759000000000
                  updated_at: 1759000000000
        '400':
          description: '`bad_request`: `name` is empty after trimming.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                bad_request:
                  summary: bad_request
                  value:
                    ok: false
                    error: name is required
                    code: bad_request
        '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 are a member of the organization but your role
            lacks the required permission, or a daemon token was used.
          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
        '404':
          description: >-
            `not_found`: The organization does not exist or you are not a
            member. CliqHub answers 404, not 403, so it does not reveal which.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                not_found:
                  summary: not_found
                  value:
                    ok: false
                    error:
                      code: not_found
                      message: Not found
        '409':
          description: '`conflict`: The organization already has a realm with this slug.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                conflict:
                  summary: conflict
                  value:
                    ok: false
                    error: Realm slug 'production' already exists in this org
                    code: conflict
        '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: 'org_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:
    RealmData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Realm UUID
        slug:
          type: string
          description: Realm slug (unique within its org)
        org_slug:
          type: string
          nullable: true
          description: Owning org slug; null for personal realms
        qualified_slug:
          type: string
          nullable: true
          description: '"org_slug.realm_slug" for org realms; null for personal realms'
        name:
          type: string
          description: Realm display name
        owner_user_id:
          type: string
          format: uuid
          description: UUID of the user who owns this realm
        created_by:
          type: string
          format: uuid
          description: UUID of the user who created this realm
        created_by_username:
          type: string
          nullable: true
          description: Username of the creator; null if account deleted
        created_at:
          type: number
          description: Epoch ms of realm creation
        updated_at:
          type: number
          description: Epoch ms of last update
        members:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Membership record UUID
              realm_id:
                type: string
                format: uuid
                description: Realm UUID this membership belongs to
              member_type:
                type: string
                enum:
                  - user
                  - daemon
                  - group
                description: Kind of principal
              member_id:
                type: string
                description: UUID of the member (user_id, daemon_id, or group_id)
              username:
                type: string
                nullable: true
                description: Username for user members; null for daemons/groups
              role:
                type: string
                enum:
                  - admin
                  - operator
                  - member
                description: Member\
              created_at:
                type: number
                description: Epoch ms when membership was created
            required:
              - id
              - realm_id
              - member_type
              - member_id
              - username
              - role
              - created_at
          description: Populated on get_by_id; absent on list
      required:
        - id
        - slug
        - org_slug
        - qualified_slug
        - name
        - owner_user_id
        - created_by
        - created_by_username
        - created_at
        - updated_at
    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.