dotsy Jobs API

openapi: 3.2.0
info:
  title: dotsy Jobs API
  version: 1.0.0
  description: 'Build, edit and publish dotsy sites over HTTP. The dashboard, the `dotsy` CLI and the MCP server all use this API.


    Production base URL: `https://api.dotsy.ai`. The **Try it** console in this reference sends requests to the origin you are reading it on, so it needs no host setting.


    ## Authentication


    Send `Authorization: Bearer ` on every request. Three kinds of token work:


    - **Account API key** (`pga_…`). Create one in the dashboard or with `POST /api/v1/account/keys`. It acts as one account.

    - **OAuth token.** MCP clients that sign in with OAuth send their opaque access token in the same header.

    - **Guest token** (`pgg_…`). `POST /api/v1/anon/sites` returns one with a new site. It works on that one site only, and publish, rename, delete, domains, imports and asset writes need an account instead.


    To choose the workspace a request acts in, send `X-Dotsy-Workspace: `. It applies to sign-in sessions and OAuth tokens. A `pga_` key is tied to one account and ignores it. A workspace you don''t belong to answers `403`.


    ## Errors


    Failures answer with a JSON body `{ "error": "", "hint": "" }`. `error` is a stable machine code, so branch on it and not on the text. Validation failures add `issues`, the list of problems, and some errors add fields that belong to them, such as `jobId` or `keys`. Every error response in this reference uses the `ApiError` schema.


    ## Lists and paging


    Each list operation that supports paging documents `limit` (1 to 1000) and `cursor`. Send `limit` to page. The response then carries `nextCursor`: a string while more results remain, and `null` on the last page. Pass it back unchanged as `cursor` to get the next page. Cursors are opaque, so don''t build or parse them.


    ## Sites, slugs and ids


    Site operations live under `/api/v1/sites/{slug}`. `{slug}` takes the site''s slug or its id (a UUID, returned as `id`). A slug changes when the site is renamed, so keep the id if you need a handle that stays put.


    - While a renamed, published site''s old slug stays reserved, it answers `301` for GET and HEAD and `308` for every other method. `Location` holds the same path under the current slug.

    - A site id answers `307` with `Location` set to the path under the current slug.


    **Follow redirects** (`curl -L`, and the default in `fetch`), then use the slug from `Location` from that point on. Slug-scoped API keys and guest tokens only work with the site''s current slug.


    Content keys and asset paths in `{key}` and `{path}` can contain `/`. Percent-encode each segment. A `/` may be sent raw or as `%2F`.


    ## Rate limits


    Writes (POST, PUT, PATCH and DELETE under `/api/v1/sites/…`) share a budget of 600 per minute per account. Raw asset uploads (`PUT …/assets-raw/…`) have their own budget of 3,000 per minute, and sending site invites has another of 30 per minute. Reads are not counted. Over budget, you get `429` with `error: "rate_limited"` and a `Retry-After` header in seconds.


    ## Long-running work


    Imports, large renames and large changesets answer `202 Accepted` with a `job` object (`id`, `kind`, `status`). Poll `GET /api/v1/sites/{slug}/jobs/{id}` every few seconds until `status` is `succeeded` or `failed`. An operation that finishes right away returns its result and no job.'
servers:
- url: /
security:
- BearerAuth: []
tags:
- name: Jobs
  description: Poll long-running work (imports, bulk content writes, renames) by job id.
paths:
  /api/v1/sites/{slug}/jobs/{id}:
    get:
      operationId: getJob
      tags:
      - Jobs
      summary: Get a background job's status
      description: Poll a job started by a 202 response (a large changeset, a large site rename, or a URL import) until `status` is `succeeded` or `failed`. `progress` and `result` depend on the job's `kind`. A job id only works on the site it was started for.
      security:
      - BearerAuth: []
      - GuestBearerAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          example: acme-studio
        required: true
        description: Site slug or site id (UUID). An old slug answers 301/308 and a site id 307 to the canonical slug path.
        name: slug
        in: path
      - schema:
          type: string
          minLength: 1
          example: content.0c9e2f4a-1b2c-4d5e-8f90-a1b2c3d4e5f6.Qm9vdHN0cmFwSm9iSWRTaWc
        required: true
        description: The `job.id` from the 202 response that started the job.
        name: id
        in: path
      responses:
        '200':
          description: The job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Your role or token can't read this kind of job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: No such site, or no such job on this site.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Background jobs are not available on this server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    Job:
      type: object
      properties:
        id:
          type: string
          description: Public job id. Poll GET /api/v1/sites/{slug}/jobs/{id}.
        kind:
          type: string
          enum:
          - import
          - content
          - rename
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
        progress:
          type: object
          properties:
            done:
              type: number
            total:
              type: number
          required:
          - done
          - total
        result:
          type: object
          additionalProperties: {}
        error:
          type: object
          properties:
            code:
              type: string
              description: '`job_failed`, or the limit the job hit (`page_limit_reached`, `storage_limit_reached`) with the fields below.'
            message:
              type: string
            hint:
              type: string
              description: 'A limit failure: what to do next (same text as `message`).'
            limit:
              type: string
              enum:
              - storage
              - pages
              description: 'A limit failure: which limit.'
            plan:
              type: string
              description: 'A limit failure: the site''s plan (`free` or `paid` today; workspace plan ids later).'
            used:
              type: number
              description: 'A limit failure: pages or bytes already used.'
            max:
              type: number
              description: 'A limit failure: the site''s limit.'
            incoming:
              type: number
              description: 'A limit failure: what the job would have added (net new pages, or bytes).'
            partial:
              type: boolean
              description: 'A limit failure: `used` is a floor (the page count was not complete).'
          required:
          - code
      required:
      - id
      - kind
      - status
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Stable machine-readable code, e.g. `invalid_body`.
          example: invalid_body
        hint:
          type: string
          description: What to do next, in plain words.
        message:
          type: string
        field:
          type: string
          description: The request field the error is about, when there is one.
        issues:
          type: array
          items: {}
          description: Validation issues (zod issues, or gate issue strings/objects).
        upgrade:
          $ref: '#/components/schemas/LimitUpgrade'
        stop:
          type: string
          description: 'On plan-limit refusals: the line an agent shows the user before it stops.'
        fix:
          type: object
          properties:
            tool:
              type: string
              enum:
              - get_plan
            args:
              type: object
              properties:
                slug:
                  type: string
          required:
          - tool
          - args
          description: 'On plan-limit refusals: the one safe next call (MCP tool + arguments).'
        requestId:
          type: string
          description: Correlation id for support (`x-dotsy-request-id`).
      required:
      - error
    LimitUpgrade:
      type: object
      properties:
        limit:
          type: string
          description: 'What ran out: `sites`, `storage`, `domains`, `pages`, `abSites`, `siteDb`, or a feature name.'
        used:
          type:
          - number
          - 'null'
        max:
          type:
          - number
          - 'null'
        incoming:
          type: number
          description: What this call would have added.
        plan:
          type: string
          enum:
          - free
          - core
          - studio
          - agency
          description: The workspace's plan today.
        requiredPlan:
          type: string
          enum:
          - free
          - core
          - studio
          - agency
          description: The cheapest workspace plan that lifts it. Absent on the top plan.
        addOn:
          type: string
          enum:
          - extraDomain
          - siteDb
          - abTest
          description: Set when one add-on lifts it (paid workspaces only).
        price:
          type:
          - object
          - 'null'
          properties:
            amount:
              type: number
            currency:
              type: string
              enum:
              - usd
            interval:
              type: string
              enum:
              - month
          required:
          - amount
          - currency
          - interval
          description: Monthly price of `addOn`, else of `requiredPlan`.
        scope:
          type: string
          enum:
          - workspace
          - site
        url:
          type: string
          description: Opens the upgrade sheet. A signed link that expires; paying still needs an owner or admin.
        canUpgrade:
          type: boolean
          description: 'false: the caller cannot pay — ask a workspace owner.'
        retryable:
          type: boolean
          description: Retrying the same call can succeed without upgrading.
      required:
      - limit
      - used
      - max
      - plan
      - price
      - scope
      - url
      - canUpgrade
      - retryable
      description: 'On plan-limit refusals: what lifts the limit and the link to do it.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Account API key (pga_…). OAuth MCP sessions use the same header with an opaque token.
    GuestBearerAuth:
      type: http
      scheme: bearer
      description: Guest token (pgg_…) returned by POST /api/v1/anon/sites. Works only on that one site, and some operations (publish, rename, delete, domains, imports, asset writes) need an account instead.