openapi: 3.2.0
info:
  title: Dokki Organizations API
  version: v1
  summary: 'The programmatic interface to Dokki workspaces: documents, tables, artifacts, files, search, agents, automations, organizations, publishing and account endpoints under https://dokki.one/api/v1.'
  description: Dokki (UEVNS PTE.
  contact:
    name: Dokki support
    email: support@dokki.one
    url: https://dokki.one/pub/docs/faq
  termsOfService: https://dokki.one/terms
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline
  x-generated: '2026-09-19'
  x-source: https://dokki.one/pub/api
  x-provider: dokki-one
servers:
- url: https://dokki.one/api/v1
  description: Production. "All public endpoints use https://dokki.one/api/v1" (https://dokki.one/pub/api/api-conventions); the reference pages state Base URL https://dokki.one with every path prefixed /api/v1, which this document folds into the server URL.
security:
- BearerAuth: []
tags:
- name: Organizations
  description: Organizations and org membership.
paths:
  /orgs:
    post:
      operationId: createOrg
      summary: Create orgs
      tags:
      - Organizations
      description: 'Create orgs. Documented at https://dokki.one/pub/api/create-orgs (required scope: org:write).'
      externalDocs:
        url: https://dokki.one/pub/api/create-orgs
      x-required-scope: org:write
      x-route-source: app/api/v1/orgs/route.ts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: The published reference does not enumerate this body's fields ("Send a JSON request body with only supported fields"); discover them from GET /api/v1/capabilities and the live contract.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    get:
      operationId: listOrgs
      summary: Get orgs
      tags:
      - Organizations
      description: 'Get orgs. Documented at https://dokki.one/pub/api/get-orgs-1 (required scope: org:read).'
      externalDocs:
        url: https://dokki.one/pub/api/get-orgs-1
      x-required-scope: org:read
      x-route-source: app/api/v1/orgs/route.ts
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Number of items, bounded by the server. The reference states "most list endpoints accept limit/offset"; verify against GET /api/v1/capabilities.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Zero-based offset. See limit.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /orgs/{org_id}:
    delete:
      operationId: deleteOrg
      summary: Delete orgs
      tags:
      - Organizations
      description: 'Delete orgs. Documented at https://dokki.one/pub/api/delete-orgs (required scope: org:write).'
      externalDocs:
        url: https://dokki.one/pub/api/delete-orgs
      x-required-scope: org:write
      x-route-source: app/api/v1/orgs/[orgId]/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    get:
      operationId: getOrg
      summary: Get orgs
      tags:
      - Organizations
      description: 'Get orgs. Documented at https://dokki.one/pub/api/get-orgs (required scope: org:read).'
      externalDocs:
        url: https://dokki.one/pub/api/get-orgs
      x-required-scope: org:read
      x-route-source: app/api/v1/orgs/[orgId]/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    patch:
      operationId: updateOrg
      summary: Update orgs
      tags:
      - Organizations
      description: 'Update orgs. Documented at https://dokki.one/pub/api/update-orgs (required scope: org:write).'
      externalDocs:
        url: https://dokki.one/pub/api/update-orgs
      x-required-scope: org:write
      x-route-source: app/api/v1/orgs/[orgId]/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: The published reference does not enumerate this body's fields ("Send a JSON request body with only supported fields"); discover them from GET /api/v1/capabilities and the live contract.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /orgs/{org_id}/members:
    post:
      operationId: addOrgMember
      summary: Add member
      tags:
      - Organizations
      description: 'Add member. Documented at https://dokki.one/pub/api/add-member-1 (required scope: org_member:write).'
      externalDocs:
        url: https://dokki.one/pub/api/add-member-1
      x-required-scope: org_member:write
      x-route-source: app/api/v1/orgs/[orgId]/members/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: The published reference does not enumerate this body's fields ("Send a JSON request body with only supported fields"); discover them from GET /api/v1/capabilities and the live contract.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    get:
      operationId: listOrgMembers
      summary: List members
      tags:
      - Organizations
      description: 'List members. Documented at https://dokki.one/pub/api/list-members (required scope: org_member:read).'
      externalDocs:
        url: https://dokki.one/pub/api/list-members
      x-required-scope: org_member:read
      x-route-source: app/api/v1/orgs/[orgId]/members/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Number of items, bounded by the server. The reference states "most list endpoints accept limit/offset"; verify against GET /api/v1/capabilities.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Zero-based offset. See limit.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /orgs/{org_id}/members/{member_id}:
    delete:
      operationId: deleteOrgMember
      summary: Remove member
      tags:
      - Organizations
      description: 'Remove member. Documented at https://dokki.one/pub/api/remove-member (required scope: org_member:write).'
      externalDocs:
        url: https://dokki.one/pub/api/remove-member
      x-required-scope: org_member:write
      x-route-source: app/api/v1/orgs/[orgId]/members/[memberId]/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      - name: member_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    patch:
      operationId: updateOrgMember
      summary: Update member
      tags:
      - Organizations
      description: 'Update member. Documented at https://dokki.one/pub/api/update-member (required scope: org_member:write).'
      externalDocs:
        url: https://dokki.one/pub/api/update-member
      x-required-scope: org_member:write
      x-route-source: app/api/v1/orgs/[orgId]/members/[memberId]/route.ts
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      - name: member_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Path identifier.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: The published reference does not enumerate this body's fields ("Send a JSON request body with only supported fields"); discover them from GET /api/v1/capabilities and the live contract.
      responses:
        '200':
          description: Successful response. JSON; preserve request_id values and treat resource identifiers as opaque UUIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid authentication (error.code unauthorized)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Insufficient scope or tenant access (error.code insufficient_scope or forbidden)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found (also returned when revealing existence would leak information)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ErrorEnvelope:
      type: object
      description: Errors use one stable shape (https://dokki.one/pub/api/pagination-errors-and-rate-limits).
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine code, e.g. unauthorized, insufficient_scope, forbidden.
              examples:
              - unauthorized
              - insufficient_scope
              - forbidden
            message:
              type: string
            request_id:
              type: string
              format: uuid
      examples:
      - error:
          code: forbidden
          message: Resource access denied
          request_id: uuid
    SuccessEnvelope:
      type: object
      description: 'Documented success shape: "Successful responses are JSON. Preserve request_id values and treat resource identifiers as opaque UUIDs."'
      properties:
        data:
          type: object
          additionalProperties: true
        request_id:
          type: string
          description: Request identifier (req_...). Log it and quote it in support tickets.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <credential>. Accepted credentials per https://dokki.one/pub/api/authentication: a Dokki API key (prefix dk_, tenant-bound to Personal or one Org, carrying the x-required-scope of each operation), a Supabase bearer access token, or a browser session. Scopes are API-key scopes, not OAuth scopes; see scopes/dokki-one-scopes.yml.'
externalDocs:
  description: Dokki API documentation
  url: https://dokki.one/pub/api