Derive Domains API

openapi: 3.2.0
info:
  title: Derive Domains API
  version: 1.0.0
  description: 'Derive''s HTTP API. Every response shape here is the single source of truth for the web client — generated from the same Zod schemas that back this reference, so the docs never drift from the running API.


    **Auth:** a session cookie (browser) or a bearer token (agents and the CLI). Most write routes are scoped to the caller''s active workspace. The `/v1` paths are the stable product surface; `/openapi.json` serves this spec and `/docs` renders it.'
tags:
- name: Domains
  description: Custom domains and vanity subdomains bound to artifacts.
paths:
  /v1/artifacts/{shortId}/domains:
    get:
      tags:
      - Domains
      summary: List an artifact's subdomains + the workspace domains it's reachable at
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: The subdomain base, the artifact's subdomains, and workspace domains.
          content:
            application/json:
              schema:
                type: object
                properties:
                  base:
                    type:
                    - string
                    - 'null'
                    description: Base host subdomains hang off (e.g. derive.to); null if disabled.
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtifactDomain'
                    description: The artifact's own vanity subdomains, managed here.
                  workspace_domains:
                    type: array
                    items:
                      type: object
                      properties:
                        host:
                          type: string
                        url:
                          type: string
                          description: This artifact's URL on that domain, including its ref.
                      required:
                      - host
                      - url
                    description: Workspace domains (its subdomain, its custom domains) this artifact is served at (read-only).
                required:
                - base
                - domains
                - workspace_domains
      operationId: getV1ArtifactsByShortIdDomains
      x-operation-id-source: derived
    put:
      tags:
      - Domains
      summary: Claim a vanity subdomain for the artifact
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: The subdomain (already claimed by this artifact).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDomain'
        '201':
          description: The newly claimed subdomain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDomain'
      operationId: putV1ArtifactsByShortIdDomains
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/domains/{host}:
    delete:
      tags:
      - Domains
      summary: Release one of the artifact's subdomains
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: host
        in: path
      responses:
        '200':
          description: The subdomain was released.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      operationId: deleteV1ArtifactsByShortIdDomainsByHost
      x-operation-id-source: derived
  /v1/workspace/domains:
    get:
      tags:
      - Domains
      summary: List the workspace's subdomain and custom domains, and what this server supports
      responses:
        '200':
          description: The subdomain base + claimed label, whether custom domains are enabled, the CNAME target, and the custom domains.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subdomain_base:
                    type:
                    - string
                    - 'null'
                    description: The base a workspace subdomain hangs off (e.g. derive.page); null when subdomains are off here.
                  subdomain:
                    anyOf:
                    - $ref: '#/components/schemas/WorkspaceSubdomain'
                    - {}
                    description: The workspace's claimed subdomain, or null.
                  enabled:
                    type: boolean
                    description: True when this server supports custom domains.
                  cname_target:
                    type:
                    - string
                    - 'null'
                    description: The CNAME target to point domains at; null when they're disabled.
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkspaceDomain'
                    description: The workspace's attached custom domains.
                required:
                - subdomain_base
                - subdomain
                - enabled
                - cname_target
                - domains
      operationId: getV1WorkspaceDomains
      x-operation-id-source: derived
    post:
      tags:
      - Domains
      summary: Attach a custom domain to the workspace
      responses:
        '200':
          description: The domain (already attached to this workspace).
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WorkspaceDomain'
                - type: object
                  properties:
                    cname_target:
                      type: string
                      description: The CNAME target to point your domain at.
                  required:
                  - cname_target
        '201':
          description: The newly attached domain, pending DNS validation.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WorkspaceDomain'
                - type: object
                  properties:
                    cname_target:
                      type: string
                      description: The CNAME target to point your domain at.
                  required:
                  - cname_target
      operationId: postV1WorkspaceDomains
      x-operation-id-source: derived
  /v1/workspace/subdomain:
    put:
      tags:
      - Domains
      summary: Claim or change the workspace's subdomain
      responses:
        '200':
          description: The subdomain (already this workspace's).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSubdomain'
        '201':
          description: The newly claimed subdomain; any previous label is released.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSubdomain'
      operationId: putV1WorkspaceSubdomain
      x-operation-id-source: derived
    delete:
      tags:
      - Domains
      summary: Release the workspace's subdomain
      responses:
        '200':
          description: The subdomain was released.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      operationId: deleteV1WorkspaceSubdomain
      x-operation-id-source: derived
  /v1/workspace/domains/{host}/refresh:
    post:
      tags:
      - Domains
      summary: Re-check a custom domain's validation status
      parameters:
      - schema:
          type: string
        required: true
        name: host
        in: path
      responses:
        '200':
          description: The domain's current status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceDomain'
      operationId: postV1WorkspaceDomainsByHostRefresh
      x-operation-id-source: derived
  /v1/workspace/domains/{host}:
    delete:
      tags:
      - Domains
      summary: Detach a custom domain from the workspace
      parameters:
      - schema:
          type: string
        required: true
        name: host
        in: path
      responses:
        '200':
          description: The domain was detached.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      operationId: deleteV1WorkspaceDomainsByHost
      x-operation-id-source: derived
components:
  schemas:
    ArtifactDomain:
      type: object
      properties:
        host:
          type: string
          description: The hostname the artifact is served at.
        url:
          type: string
          description: That host with scheme, ready to link to.
        kind:
          type: string
          enum:
          - subdomain
          - custom
          description: '"subdomain" = a vanity <label>.<base>; "custom" = a workspace custom domain.'
        status:
          type: string
          enum:
          - active
          - pending
          - error
          description: '"active" = serving; "pending" = awaiting DNS/cert; "error" = validation failed.'
        created_at:
          type: string
      required:
      - host
      - url
      - kind
      - status
      - created_at
    WorkspaceDomain:
      type: object
      properties:
        host:
          type: string
          description: The custom domain attached to the workspace.
        status:
          type: string
          enum:
          - active
          - pending
          - error
          description: '"active" = serving; "pending" = awaiting DNS/cert; "error" = validation failed.'
        records:
          type: array
          items:
            $ref: '#/components/schemas/DomainDnsRecord'
          description: DNS records to add while pending; absent once the domain is active.
        created_at:
          type: string
      required:
      - host
      - status
      - created_at
    DomainDnsRecord:
      type: object
      properties:
        type:
          type: string
          description: DNS record type to create (e.g. CNAME).
        name:
          type: string
          description: The name/host to create the DNS record at.
        value:
          type: string
          description: The value the DNS record should point at.
      required:
      - type
      - name
      - value
    WorkspaceSubdomain:
      type: object
      properties:
        host:
          type: string
          description: The full host, `<label>.<base>`.
        label:
          type: string
          description: The label the workspace chose.
        url:
          type: string
          description: The host with scheme; artifacts live at `<url>/<ref>`.
        created_at:
          type: string
      required:
      - host
      - label
      - url
      - created_at