spintax-net Sites API

openapi: 3.2.0
info:
  title: clx management Sites 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: Sites
paths:
  /v1/sites:
    get:
      summary: Sites (scope sites); `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:
                  sites:
                    type: array
                    items:
                      $ref: '#/components/schemas/Site'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: getV1Sites
      x-operation-id-source: derived
    post:
      summary: Add a site (scope sites) — the zone is found in the account, the route made…
      description: 'The account must be `ready`. The answer carries the snippet at once; `config` turns

        `synced` once the worker has the site (seconds), and the counter answers from then on.


        With `collector_host` it is an external site — one not on Cloudflare (Pro only,

        docs/spec.md §5): its `host` must be in no zone of the account (`invalid_request`), the

        route is made on `collector_host`, a host of the account''s zones that already answers

        through Cloudflare (clx makes no DNS record) and is no link host. Its snippet sends a CORS

        request to that host, so a page whose CSP limits `connect-src` (or `script-src`, for the

        tag) must allow it. `limit_reached` (limit 0) on free; `update_required` while the

        account''s clx-edge predates external sites; `operation_in_progress` while another

        operation holds the account.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              - host
              properties:
                account_id:
                  type: string
                host:
                  type: string
                  description: example.com or a subdomain of a zone in that account; with collector_host, a host in none
                collector_host:
                  type: string
                  description: 'makes an external site: a host of a zone in that account, other than host'
                excluded_paths:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    pattern: ^/
      responses:
        '202':
          description: Added
          content:
            application/json:
              schema:
                type: object
                properties:
                  site:
                    $ref: '#/components/schemas/Site'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: postV1Sites
      x-operation-id-source: derived
  /v1/sites/{id}:
    get:
      summary: One site (scope sites)
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  site:
                    $ref: '#/components/schemas/Site'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: getV1SitesById
      x-operation-id-source: derived
    patch:
      summary: Change the excluded paths (scope sites)
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                excluded_paths:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    pattern: ^/
      responses:
        '200':
          description: Changed
          content:
            application/json:
              schema:
                type: object
                properties:
                  site:
                    $ref: '#/components/schemas/Site'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: patchV1SitesById
      x-operation-id-source: derived
    delete:
      summary: Remove the site's routes (scope sites); the site stays as `deleted`, its totals…
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  site:
                    $ref: '#/components/schemas/Site'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: deleteV1SitesById
      x-operation-id-source: derived
  /v1/sites/{id}/report:
    get:
      summary: Totals and series of the site (scope reports); with breakdowns=1 also the top…
      parameters:
      - $ref: '#/components/parameters/Id'
      - name: period
        in: query
        schema:
          type: string
          enum:
          - today
          - 7d
          - 30d
          default: today
      - name: breakdowns
        in: query
        schema:
          type: string
          enum:
          - '1'
        description: read the breakdowns from the account's database (cached 5 minutes)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  report:
                    $ref: '#/components/schemas/Report'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: getV1SitesByIdReport
      x-operation-id-source: derived
  /v1/sites/{id}/rotate:
    post:
      summary: A new path, names and snippet (scope sites); the old path is counted for 30…
      description: An external site keeps its path for life (`invalid_request`).
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Rotated
          content:
            application/json:
              schema:
                type: object
                properties:
                  site:
                    $ref: '#/components/schemas/Site'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Sites
      operationId: postV1SitesByIdRotate
      x-operation-id-source: derived
components:
  schemas:
    Report:
      type: object
      properties:
        period:
          type: string
          enum:
          - today
          - 7d
          - 30d
        from:
          type: string
          format: date
          description: first UTC day
        to:
          type: string
          format: date
          description: last UTC day — today
        as_of:
          type:
          - string
          - 'null'
          format: date-time
          description: 'today is counted up to this moment. A site: the end of the latest closed hour the worker sent (hours arrive up to an hour late), null before its first push. A link: the moment of the live read of the account''s database'
        totals:
          type: object
          properties:
            views:
              type: integer
            bots:
              type: integer
            visitors:
              type: integer
              description: the sum of daily unique visitors
        series:
          type: array
          description: today — one point per hour up to as_of; 7d/30d — one per day (with visitors)
          items:
            type: object
            properties:
              at:
                type: string
                format: date-time
              views:
                type: integer
              bots:
                type: integer
              visitors:
                type: integer
        incomplete:
          type: boolean
          description: today's hours were refused over the account's write budget; daily totals stay exact
        breakdowns:
          type:
          - object
          - 'null'
          description: only with breakdowns=1; read from the account's own database, null when unavailable
          properties:
            pages:
              $ref: '#/components/schemas/Top'
            sources:
              $ref: '#/components/schemas/Top'
            countries:
              $ref: '#/components/schemas/Top'
            devices:
              $ref: '#/components/schemas/Top'
            browsers:
              $ref: '#/components/schemas/Top'
            os:
              $ref: '#/components/schemas/Top'
            bots:
              $ref: '#/components/schemas/Top'
            flows:
              type: array
              maxItems: 200
              description: 'a link only: clicks by source and destination together, the top 200 by count. `to` is where the clicks were sent: the matched rule''s conditions and URL, `AT,DE;mobile>https://…` (sorted; past 40 countries the first 40 and `+N#<fingerprint of the whole list>`), or `>https://…` for the main URL (the first 512 characters, also the keys of a link''s `pages`); "" for clicks counted by a worker that did not record it yet, "(other)" for what went over the detail caps'
              items:
                type: object
                properties:
                  source:
                    type: string
                  to:
                    type: string
                  n:
                    type: integer
        unavailable:
          type: string
          enum:
          - not_installed
          - cloudflare
          - rate_limited
          description: 'why breakdowns (and a link''s today) are not there: the worker is not installed or the token is gone; Cloudflare failed or took over 5 s; over 30 reads of the account databases a minute for this clx user (each cached 5 minutes)'
    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
    Top:
      type: array
      maxItems: 10
      description: the top 10 by count; "(other)" holds what went over the detail caps
      items:
        type: object
        properties:
          key:
            type: string
          n:
            type: integer
    Site:
      type: object
      properties:
        id:
          type: string
        account_id:
          type: string
        host:
          type: string
        kind:
          type: string
          enum:
          - zone
          - external
          description: zone — the host is in a zone of the account and the counter answers on it; external — a site not on Cloudflare (Pro), counted on collector_host (docs/spec.md §5)
        collector_host:
          type:
          - string
          - 'null'
          description: 'an external site''s: the host of the account''s zones its beacons go to; null for zone'
        state:
          type: string
          enum:
          - route_pending
          - active
          - route_conflict
          - deleted
          description: route_pending — the route is still to be made (the cron retries); route_conflict — another worker holds the pattern, see error
        path:
          type: string
          description: the per-site path the counter answers under, e.g. /lumora or /kavi/tesomu
        snippet:
          type:
          - object
          - 'null'
          description: Embed one of the two at build time; stable until rotate (an external site is never rotated)
          properties:
            inline:
              type: string
              description: <script>…</script>, under 600 bytes for a zone site; an external site's also names its collector host
            script_tag:
              type: string
              description: <script src="/<path>/<s>.js"> with defer (the order of the attributes varies by site); an external site's src is https://<collector_host>/<path>/<s>.js
        excluded_paths:
          type: array
          items:
            type: string
        config:
          type: string
          enum:
          - pending
          - synced
          description: whether the worker has this version of the site yet
        paused_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'set while the site is beyond the free plan''s limits (docs/spec.md §18): it is not counted and cannot be changed'
        retiring:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              until:
                type: string
                format: date-time
          description: old paths still counted after a rotation
        error:
          type:
          - object
          - 'null'
        created_at:
          type: string
          format: date-time
        views_7d:
          type: array
          items:
            type: integer
          minItems: 7
          maxItems: 7
          description: views of each of the last 7 closed UTC days, oldest first (GET /v1/sites only, and only with the reports scope)
        views_today:
          type: integer
          description: today's views so far, as of the last hour the worker sent (GET /v1/sites only, and only with the reports scope)
        counted:
          type: boolean
          description: whether the counter has counted a view of this site yet (GET /v1/sites only, and only with the reports scope)
  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