spintax-net Accounts API

openapi: 3.2.0
info:
  title: clx management Accounts API
  version: 0.8.0
  description: 'The /v1 API of clx (docs/spec.md §15). The clx.cx page is a thin client over the same endpoints.

    Authorization: `Bearer ` from a signed-in page, or `Bearer clx_…` — an API key

    (one on the `free` plan, up to 5 on `api`). Every POST, PUT, PATCH and DELETE takes an `Idempotency-Key` header, required

    with an API key; a repeat with the same body replays the first answer for 24 hours.

    Errors: `{ "error": { "code", "message", "details"? } }`. This file grows with each stage; a

    test checks that every route in the code is here and back.'
servers:
- url: https://clx.cx
security:
- bearer: []
tags:
- name: Accounts
paths:
  /v1/accounts:
    get:
      summary: Connected Cloudflare accounts (scope accounts or sites)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: getV1Accounts
      x-operation-id-source: derived
    post:
      summary: Connect a Cloudflare account with a bootstrap token (scope accounts)
      description: 'The bootstrap token (Account Settings — Read + Account API Tokens — Edit, which the API names

        Write; one day) is used

        within this request and deleted; it is never stored. The account then goes on to the

        install of clx-edge (§4) — poll GET for its state: `installing`, then `ready` once the script,

        its database and cron are in place (seconds; the worker''s own confirmation may follow

        minutes later, or never — then `error.warnings` says `not_confirmed`), or `connected` with an `error`.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - cf_account_id
              - bootstrap_token
              properties:
                cf_account_id:
                  type: string
                  pattern: ^[0-9a-f]{32}$
                bootstrap_token:
                  type: string
      responses:
        '202':
          description: Connected
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: postV1Accounts
      x-operation-id-source: derived
  /v1/accounts/{id}:
    get:
      summary: One connected account (scope accounts or sites), with its latest operation and…
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: getV1AccountsById
      x-operation-id-source: derived
    delete:
      summary: Disconnect (scope accounts) — delete clx-edge and its database, then the record
      description: 'The answer names the working token to revoke in Cloudflare (it cannot delete itself), and in

        `left` whatever clx could not delete — the token is revoked, a right is missing, or the

        worker was changed outside clx — for the user to remove by hand.'
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Disconnected
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  revoke_token:
                    type:
                    - string
                    - 'null'
                  left:
                    type: array
                    items:
                      type: string
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: deleteV1AccountsById
      x-operation-id-source: derived
  /v1/accounts/{id}/zones:
    get:
      summary: The account's zones (scope accounts or sites) — to pick a site's or link host's…
      description: 'Read live from Cloudflare with the working token, sorted by name; at most 1,000, `truncated`

        past that. A host is still checked against its zone when it is added.'
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  zones:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        status:
                          type: string
                          description: 'Cloudflare''s zone status: active, pending, …'
                  truncated:
                    type: boolean
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: getV1AccountsByIdZones
      x-operation-id-source: derived
  /v1/accounts/{id}/install:
    post:
      summary: Install clx-edge again (scope accounts) — after a failed install, or to…
      description: 'The recorded database is kept; the worker gets a new key (the previous one is accepted for a

        day). A clx-edge worker or database clx did not create is never touched (`name_taken`), nor

        a worker changed outside clx (`resource_drift`). Poll GET for the state.'
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Started
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/Account'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: postV1AccountsByIdInstall
      x-operation-id-source: derived
  /v1/accounts/{id}/token:
    post:
      summary: Renew the working token with a new bootstrap token (scope accounts)
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - bootstrap_token
              properties:
                bootstrap_token:
                  type: string
      responses:
        '200':
          description: Renewed
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Accounts
      operationId: postV1AccountsByIdToken
      x-operation-id-source: derived
components:
  schemas:
    LinkHost:
      type: object
      properties:
        id:
          type: string
        account_id:
          type: string
        site_id:
          type:
          - string
          - 'null'
          description: the site it was made for; null for a host the user named
        host:
          type: string
          description: k7q.example.com — a random 3-character label under the site's host, or the named host
        state:
          type: string
          enum:
          - pending
          - active
          - conflict
          - deleted
          description: pending — its custom domain is being made (the cron retries); active — Cloudflare made it, with its DNS record and certificate; conflict — see error
        config:
          type: string
          enum:
          - pending
          - synced
          description: whether the worker has it yet; short links answer once active and synced
        error:
          type:
          - object
          - 'null'
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: 'Stable codes: unauthorized, invalid_request, not_found, payload_too_large,

                limit_reached, service_full, idempotency_conflict, operation_in_progress,

                scope_required, session_required, key_already_issued,

                account_taken, already_connected, account_not_ready, invalid_bootstrap,

                bootstrap_permission_error, permission_catalog, orphan_not_deleted,

                token_rights_mismatch, token_check_failed, renew_lost, rate_limited, cloudflare_unavailable,

                not_configured, internal. In an account''s or operation''s `error` (the install, §4):

                name_taken, resource_drift, cron_limit, permission_error, revoked, self_check_timeout,

                credentials_missing, credentials_unreadable (clx cannot open the stored token),

                cloudflare_error. Sites: zone_not_found, site_exists, route_conflict, site_not_active,

                update_required (external sites need a newer clx-edge),

                route_not_ours (a route clx made was changed outside clx and left in place).

                Sign-up: email_unconfirmed (POST /v1/accounts before the address is confirmed),

                invalid_password, balance_not_empty (DELETE /v1/me while money is on the balance or the partner wallet or still moving, §18).

                Billing (docs/spec.md §18): insufficient_balance (Pro needs $9 on the balance), invoice_limit (3 pending top-ups),

                payments_unavailable (crypto top-ups not set up or the processor down),

                refund_unavailable (a top-up never credited, older than 90 days or refunded

                already), refund_open (a refund of that top-up is asked for already), paused (an

                object beyond the free plan''s limits: it can be read and deleted, not changed).

                Links: link_exists (the code is taken on that link host), link_host_not_ready (links go

                on an active host only), link_host_in_use

                (DELETE /v1/link-hosts/{id} while live links are on it). In a link host''s `error`:

                dns_record_exists (the named host already has a DNS record — never taken over),

                domain_taken (another worker''s custom domain), domain_not_ours.

                '
            message:
              type: string
            details:
              type: object
    Account:
      type: object
      properties:
        id:
          type: string
        cf_account_id:
          type: string
        name:
          type: string
        state:
          type: string
          enum:
          - pending
          - bootstrap_lost
          - connected
          - installing
          - ready
          - permission_error
          - revoked
          - resource_drift
          - no_connection
          description: 'pending — the connect is running, or stopped on a passing failure (5xx other than token_rights_mismatch, token_check_failed, permission_catalog, which end it) and waits for the same request again (same Idempotency-Key); bootstrap_lost — a connect left pending for an hour, or one that died before clx stored its working token: revoke the token its error names and connect again; connected — token ready, clx-edge not installed; installing — the install runs; ready — installed and serving, go on (the worker confirms itself on its first cron: meanwhile `operation` shows the install at step selfcheck, for up to 15 minutes, and if no confirmation comes error.warnings says not_confirmed — nothing to wait for either way); no_connection — installed, but no push from the worker for 26 hours (sites can still be added; its next push makes it ready again)'
        token:
          type:
          - object
          - 'null'
          properties:
            name:
              type: string
              description: clx-<operation id>
            expires_at:
              type: string
              format: date-time
        error:
          type:
          - object
          - 'null'
          description: code and details, or warnings such as bootstrap_not_deleted
        edge:
          type:
          - object
          - 'null'
          description: The installed clx-edge, from its upload on (the worker's own confirmation is not needed)
          properties:
            bundle:
              type: string
              description: sha256 of the bundle
            up_to_date:
              type: boolean
            schema:
              type: integer
            installed_at:
              type: string
              format: date-time
        push:
          type:
          - object
          - 'null'
          description: The worker's own report from its last push of totals (hourly)
          properties:
            at:
              type: string
              format: date-time
            bundle:
              type: string
              description: sha256 of the bundle the worker runs
            schema:
              type:
              - integer
              - 'null'
            queue:
              type: integer
              description: queue parts and final days waiting to be sent
            error:
              type:
              - string
              - 'null'
              description: the worker's last error
            dropped:
              type: object
              additionalProperties:
                type: integer
              description: 'items dropped unsent, by reason: budget, invalid, unknown_target, too_old, busy, expired'
        advice:
          type:
          - object
          - 'null'
          description: When to move this Cloudflare account to Workers Paid, from its measured use over the last 7 complete UTC days; on an account already on Workers Paid (`paid`), only the current size of clx-edge; recomputed daily, null until first computed
          properties:
            level:
              type: string
              enum:
              - ok
              - watch
              - upgrade_soon
              - over
              description: 'the worst metric: over — a limit was reached (or the database is at backpressure, 400 MB); upgrade_soon — busiest day ≥ 80% or the limit within 7 days; watch — ≥ 60% or within 30 days'
            metric:
              type:
              - string
              - 'null'
              enum:
              - requests
              - writes
              - reads
              - size
              - null
            metrics:
              type: object
              description: requests, writes, reads — per day for the whole account, against 100,000 / 100,000 / 5,000,000; size — clx-edge now, against 500 MB (on Workers Paid against 400 MB, where the worker stops keeping details)
              additionalProperties:
                type: object
                properties:
                  level:
                    type: string
                    enum:
                    - ok
                    - watch
                    - upgrade_soon
                    - over
                  limit:
                    type: integer
                  busiest:
                    type: object
                    properties:
                      day:
                        type:
                        - string
                        - 'null'
                        format: date
                      value:
                        type: integer
                  forecast:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: the day the trend reaches the limit, when within 30 days
            unavailable:
              type: array
              items:
                type: string
                enum:
                - analytics
                - size
              description: what could not be read — not guessed
            suggest:
              type: string
              enum:
              - shorter_hourly_retention
              description: size alone is the problem
            paid:
              type: boolean
              enum:
              - true
              description: 'the account is on Workers Paid (read from its entitlements): requests, writes and reads are not judged — no daily limit stops them — only size is, and no e-mail is sent'
            at:
              type: string
              format: date-time
        operation:
          type:
          - object
          - 'null'
          description: The latest operation on the account (GET /v1/accounts/{id} only)
          properties:
            kind:
              type: string
              enum:
              - connect
              - renew
              - install
              - update
              - disconnect
            state:
              type: string
              enum:
              - running
              - done
              - failed
            step:
              type: string
            error:
              type:
              - object
              - 'null'
            updated_at:
              type: string
              format: date-time
        link_hosts:
          type: array
          items:
            $ref: '#/components/schemas/LinkHost'
          description: The account's link hosts (GET /v1/accounts/{id} only)
        paused_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'set while the account is beyond the free plan''s limits (docs/spec.md §18): its sites and links are withdrawn from the worker, nothing new can be added'
        created_at:
          type: string
          format: date-time
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 200
        pattern: ^[!-~]{1,200}$
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,64}$
        description: 'an id of clx: 22 characters of base64url'
  responses:
    Error:
      description: An error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer