Capgo Organizations API

openapi: 3.2.0
info:
  title: Capgo Public Organizations API
  summary: REST API for managing Capgo organizations, apps, live update channels, bundles, devices, analytics, and API keys.
  description: 'Use this API to automate Capgo Cloud instead of clicking through the dashboard.


    ## Authentication


    Send a Capgo API key in the `x-api-key` header, or as `Authorization: Bearer `. The legacy `authorization` header with the raw key (no Bearer prefix) is still accepted. Generate keys at https://console.capgo.app/settings/organization/api-keys. Each key carries role bindings (organization, app or channel roles such as `org_admin`, `app_developer` or `app_reader`), so a key only reaches the organizations, apps and channels it was granted.


    Agents can also get a key through OAuth 2.0: authorization code with PKCE (S256) and dynamic client registration, issuer `https://capgo.app` (metadata at https://capgo.app/.well-known/oauth-authorization-server). The user picks which organizations to grant on the consent screen, and the access token is a Capgo API key sent as a Bearer token. The only OAuth scope is `capgo`; access is narrowed by the organizations the user selects, not by scope.


    ## Versioning and deprecation


    The API is versioned by date. Pin a version with the `capgo_api` request header, for example `capgo_api: 2025-10-01`; without the header you get the default version, currently `2025-10-01`. Changes within a version are additive: new endpoints, new optional parameters and new response fields. A breaking change ships as a new dated version, and clients pinned to an older date keep the old behavior. An unknown or malformed version is rejected with `400 unsupported_capgo_api_version` or `400 invalid_capgo_api_version`. Removing an operation or field is a breaking change, so it only happens in a new dated version. Nothing is deprecated today. When something is, the operation will be marked `deprecated: true` in this spec, its responses will carry the `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with the date the old behavior ends, and the change will be announced in the release notes at https://github.com/Cap-go/capgo.app/releases.


    ## Rate limits


    Each API key may send 2,000 requests per minute (20,000 per minute on bundle upload routes). Responses report the quota with the `RateLimit-Policy` and `RateLimit` headers (IETF draft-ietf-httpapi-ratelimit-headers), for example `RateLimit-Policy: "apikey";q=2000;w=60` and `RateLimit: "apikey";r=1995;t=42` (r = requests left, t = seconds until the window resets). An IP address that sends 20 invalid keys within 15 minutes is blocked for 15 minutes. A 429 response includes `Retry-After` in seconds.


    ## Errors


    Every error response is JSON with a machine-readable `error` code, a human-readable `message`, and optional `moreInfo` details, for example `{"error":"invalid_apikey","message":"Invalid apikey","moreInfo":{}}`.'
  version: '2025-10-01'
servers:
- url: https://api.capgo.app
  description: Production
security:
- CapgoApiKeyAuth: []
- CapgoBearerAuth: []
- CapgoOAuth:
  - capgo
- CapgoLegacyAuthorization: []
tags:
- name: Organizations
  description: Organization CRUD and metadata.
paths:
  /organization/:
    get:
      tags:
      - Organizations
      operationId: getOrganizations
      summary: List accessible organizations or fetch one organization by `orgId`
      parameters:
      - name: orgId
        in: query
        description: Optional organization identifier for a single-organization lookup.
        schema:
          type: string
      - $ref: '#/components/parameters/CapgoApiVersion'
      responses:
        '200':
          description: Organization data.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OrganizationEnvelope'
                - $ref: '#/components/schemas/OrganizationListEnvelope'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          description: The API key is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '403':
          description: The API key is valid but lacks the required scope or org access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          description: Too many requests. Back off and retry later.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected Capgo server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        default:
          description: Any other error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: List organizations the API key can access, or fetch one organization when `orgId` is provided. Use this to resolve the org scope before creating apps or inviting members.
    post:
      tags:
      - Organizations
      operationId: createOrganization
      summary: Create a new organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationCreate'
      responses:
        '200':
          description: Organization created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          description: The request body or query parameters were invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          description: The API key is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '403':
          description: The API key is valid but lacks the required scope or org access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          description: Too many requests. Back off and retry later.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected Capgo server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        default:
          description: Any other error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Create a new organization owned by the authenticated account. Requires a name and returns a status payload when the organization is stored.
      parameters:
      - $ref: '#/components/parameters/CapgoApiVersion'
    put:
      tags:
      - Organizations
      operationId: updateOrganization
      summary: Update an organization. Admin access is required
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUpdate'
      responses:
        '200':
          description: Organization updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          description: The request body or query parameters were invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          description: The API key is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '403':
          description: The API key is valid but lacks the required scope or org access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          description: Too many requests. Back off and retry later.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected Capgo server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        default:
          description: Any other error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Update organization metadata such as name or settings. Admin access on the target organization is required.
      parameters:
      - $ref: '#/components/parameters/CapgoApiVersion'
    delete:
      tags:
      - Organizations
      operationId: deleteOrganization
      summary: Delete an organization by query parameter
      parameters:
      - name: orgId
        in: query
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/CapgoApiVersion'
      responses:
        '200':
          description: Organization deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          description: The API key is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '403':
          description: The API key is valid but lacks the required scope or org access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          description: Too many requests. Back off and retry later.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected Capgo server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        default:
          description: Any other error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Permanently delete an organization identified by query parameter. This removes the org and is not reversible.
components:
  headers:
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimit-Policy:
      description: 'Quota policy (draft-ietf-httpapi-ratelimit-headers): `"<policy>";q=<requests>;w=<window seconds>`.'
      schema:
        type: string
      example: '"apikey";q=2000;w=60'
    RateLimit:
      description: 'Remaining quota for the current window (draft-ietf-httpapi-ratelimit-headers): `"<policy>";r=<requests left>;t=<seconds until reset>`.'
      schema:
        type: string
      example: '"apikey";r=1995;t=42'
  schemas:
    OrganizationUpdate:
      type: object
      additionalProperties: false
      properties:
        orgId:
          type: string
        logo:
          type: string
          format: uri
        name:
          type: string
        management_email:
          type: string
          format: email
      required:
      - orgId
    StatusResponse:
      type: object
      properties:
        status:
          type: string
      required:
      - status
      additionalProperties: true
    ErrorResponse:
      type: object
      description: Error body returned by every 4xx and 5xx response.
      properties:
        error:
          type: string
          description: Machine-readable error code, for example `invalid_apikey`, `no_key_provided`, `too_many_requests`.
        message:
          type: string
          description: Human-readable explanation.
        moreInfo:
          type: object
          description: Optional structured details, such as `retryAfterSeconds` on a 429.
          additionalProperties: true
      required:
      - error
      - message
      additionalProperties: true
    OrganizationEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Organization'
      required:
      - data
    OrganizationCreate:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
      required:
      - name
    OrganizationListEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Organization'
      required:
      - data
    Organization:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        logo:
          type:
          - string
          - 'null'
          format: uri
        management_email:
          type: string
          format: email
        customer_id:
          type:
          - string
          - 'null'
      required:
      - id
      - name
  parameters:
    CapgoApiVersion:
      name: capgo_api
      in: header
      required: false
      description: Date-based API version to pin. Defaults to the current version when omitted.
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
        default: '2025-10-01'
      example: '2025-10-01'
  securitySchemes:
    CapgoApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Send the raw Capgo API key in the `x-api-key` header. Generate or rotate keys at https://console.capgo.app/settings/organization/api-keys.
    CapgoBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Capgo API key
      description: 'Send a Capgo API key, or an access token from the Capgo OAuth flow, as `Authorization: Bearer <key>`.'
    CapgoOAuth:
      type: oauth2
      description: 'OAuth 2.0 authorization code flow with PKCE (S256) and dynamic client registration (https://api.capgo.app/mcp/oauth/register). Issuer: https://capgo.app. The access token is a Capgo API key limited to the organizations the user selects on the consent screen; send it as a Bearer token.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.capgo.app/mcp/oauth/authorize
          tokenUrl: https://api.capgo.app/mcp/oauth/token
          scopes:
            capgo: Act on the organizations the user selects on the consent screen, with the user's role in each of them.
    CapgoLegacyAuthorization:
      type: apiKey
      in: header
      name: authorization
      description: Legacy raw API key in the `authorization` header without a Bearer prefix. Prefer `x-api-key`.
externalDocs:
  description: Capgo public API documentation
  url: https://capgo.app/docs/public-api/