spintax-net Link Hosts API

openapi: 3.2.0
info:
  title: clx management Link Hosts 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: Link Hosts
paths:
  /v1/link-hosts:
    get:
      summary: Link hosts (scope links); `account_id` narrows to one account
      parameters:
      - name: account_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  link_hosts:
                    type: array
                    items:
                      $ref: '#/components/schemas/LinkHost'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Link Hosts
      operationId: getV1LinkHosts
      x-operation-id-source: derived
    post:
      summary: Add a link host (scope links) — one per site if wished; clx makes it a custom…
      description: '`{site_id}` makes `.` (a leading `www.` dropped) with a random label of 3

        characters; `{account_id, host}` takes a host you name, in one of the account''s zones. The

        account must be `ready`. clx makes the host a Workers Custom Domain of clx-edge: Cloudflare

        creates its DNS record and certificate, so you create no record. A host that already has a

        DNS record is never taken over: a random label is tried again with another, a named host

        ends `conflict` (`dns_record_exists`). Answers `202`; poll GET until `state` is `active` and

        `config` is `synced` (usually seconds). Up to the plan''s site limit per user. An external

        site has no zone for `{site_id}` (`invalid_request`), and a site''s host or collector host

        cannot be a link host.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              oneOf:
              - required:
                - site_id
                not:
                  anyOf:
                  - required:
                    - account_id
                  - required:
                    - host
              - required:
                - account_id
                - host
                not:
                  required:
                  - site_id
              properties:
                site_id:
                  type: string
                  description: the site to make a host for; alone
                account_id:
                  type: string
                  description: with host
                host:
                  type: string
                  description: 'with account_id: a host of a zone in that account, such as k7q.example.com'
      responses:
        '202':
          description: Started
          content:
            application/json:
              schema:
                type: object
                properties:
                  link_host:
                    $ref: '#/components/schemas/LinkHost'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Link Hosts
      operationId: postV1LinkHosts
      x-operation-id-source: derived
  /v1/link-hosts/{id}:
    get:
      summary: One link host (scope links)
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  link_host:
                    $ref: '#/components/schemas/LinkHost'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Link Hosts
      operationId: getV1LinkHostsById
      x-operation-id-source: derived
    delete:
      summary: Delete a link host (scope links) — refused while live links are on it; its…
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  link_host:
                    $ref: '#/components/schemas/LinkHost'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Link Hosts
      operationId: deleteV1LinkHostsById
      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
  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