CrawlCheck Log API

openapi: 3.2.0
info:
  title: Crawlcheck Io Log API
  version: '1'
  contact:
    name: CrawlCheck
    url: https://crawlcheck.io/policy
    email: hello@crawlcheck.io
  license:
    name: Terms
    url: https://crawlcheck.io/policy
  x-core-contract:
    promise: 'These operations are the core contract. They stay at /api/v1 and keep answering for at least 180 days after any /api/v2 is announced; their stable fields change only in a new major version, and their provisional fields only after 30 days'' notice, per /docs/api/compatibility. Verifying what they return needs none of these calls: crawlcheck-verify.mjs checks a document on your machine against the published keys (/.well-known/http-message-signatures-directory) and the rotation record, read once with --online or saved for --keys. Everything else documented here is useful but secondary, and may change with the notice its fields'' tags promise.'
    operations:
    - method: GET
      path: /api/v1/resolve
      operationId: resolveDomainV1
    - method: POST
      path: /api/v1/resolve
      operationId: resolveBatchV1
    - method: POST
      path: /api/v1/preflight
      operationId: preflightV1
    - method: GET
      path: /api/v1/decisions/{sha256}
      operationId: decisionCheckV1
    - method: GET
      path: /api/v1/revocations
      operationId: revocations
    - method: GET
      path: /api/v1/visitor
      operationId: visitorResolveV1
    - method: POST
      path: /api/v1/visitor
      operationId: visitorResolveBatchV1
    - method: GET
      path: /api/v1/mcp/scan
      operationId: mcpScanUrl
    - method: POST
      path: /api/v1/mcp/lock/check
      operationId: mcpLockCheck
    list: https://crawlcheck.io/api/v1/core
  description: 'Operations tagged Log across 2 of this provider''s published API definitions: crawlcheck-io-openapi.json, crawlcheck-io-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://crawlcheck.io
tags:
- name: Log
paths:
  /api/v1/log:
    get:
      operationId: resolveLog
      summary: 'The Resolve transparency log: the latest signed tree head (crawlcheck-log-sth)…'
      responses:
        '200':
          description: log head
          content:
            application/json:
              examples:
                worked:
                  value:
                    kind: crawlcheck-log
                    v: 1
                    log_id: crawlcheck-resolve-log-v1
                    head:
                      kind: crawlcheck-log-sth
                      v: 1
                      log_id: crawlcheck-resolve-log-v1
                      batch: 12
                      first_index: 5210
                      batch_size: 318
                      tree_size: 5528
                      batch_root: …
                      prev_sth_sha256: …
                      created_at: '2026-10-07T13:02:10.000Z'
                      sha256: …
                      signature: …
                    batches: 13
                    tree_size: 5528
                    last_witnessed:
                      batch: 12
                      sth_sha256: …
                      at: '2026-10-07T13:51:40.000Z'
                      witness: github-actions:emmanuelorta/crawlcheck/.github/workflows/log-witness.yml
              schema:
                type:
                - object
                - 'null'
                properties:
                  kind:
                    type:
                    - string
                    - 'null'
                  v:
                    type:
                    - number
                    - 'null'
                  log_id:
                    type:
                    - string
                    - 'null'
                  head:
                    type:
                    - object
                    - 'null'
                    properties:
                      kind:
                        type:
                        - string
                        - 'null'
                      v:
                        type:
                        - number
                        - 'null'
                      log_id:
                        type:
                        - string
                        - 'null'
                      batch:
                        type:
                        - number
                        - 'null'
                      first_index:
                        type:
                        - number
                        - 'null'
                      batch_size:
                        type:
                        - number
                        - 'null'
                      tree_size:
                        type:
                        - number
                        - 'null'
                      batch_root: {}
                      prev_sth_sha256: {}
                      created_at:
                        type:
                        - string
                        - 'null'
                      sha256: {}
                      signature: {}
                    additionalProperties: true
                  batches:
                    type:
                    - number
                    - 'null'
                  tree_size:
                    type:
                    - number
                    - 'null'
                  last_witnessed:
                    type:
                    - object
                    - 'null'
                    properties:
                      batch:
                        type:
                        - number
                        - 'null'
                      sth_sha256: {}
                      at:
                        type:
                        - string
                        - 'null'
                      witness:
                        type:
                        - string
                        - 'null'
                    additionalProperties: true
                additionalProperties: true
                x-schema-source: worked-example
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s https://crawlcheck.io/api/v1/log
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/sths:
    get:
      operationId: resolveLogSths
      summary: 'Up to 200 signed tree heads in one answer, newest first from ?to (default: the…'
      parameters:
      - name: to
        in: query
        schema:
          type: integer
      - name: n
        in: query
        schema:
          type: integer
          maximum: 200
      responses:
        '200':
          description: sths
          content:
            application/json:
              examples:
                worked:
                  value:
                    kind: crawlcheck-log-sths
                    log_id: crawlcheck-resolve-log-v1
                    to: 12
                    n: 3
                    head_batch: 40
                    sths:
                    - kind: crawlcheck-log-sth
                      batch: 12
                      sha256: …
                      signature: …
                    - kind: crawlcheck-log-sth
                      batch: 11
                      sha256: …
                      signature: …
                    - kind: crawlcheck-log-sth
                      batch: 10
                      sha256: …
                      signature: …
              schema:
                type:
                - object
                - 'null'
                properties:
                  kind:
                    type:
                    - string
                    - 'null'
                  log_id:
                    type:
                    - string
                    - 'null'
                  to:
                    type:
                    - number
                    - 'null'
                  n:
                    type:
                    - number
                    - 'null'
                  head_batch:
                    type:
                    - number
                    - 'null'
                  sths:
                    type:
                    - array
                    - 'null'
                    items:
                      type:
                      - object
                      - 'null'
                      properties:
                        kind:
                          type:
                          - string
                          - 'null'
                        batch:
                          type:
                          - number
                          - 'null'
                        sha256: {}
                        signature: {}
                      additionalProperties: true
                additionalProperties: true
                x-schema-source: worked-example
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s 'https://crawlcheck.io/api/v1/log/sths?to=12&n=3'
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/sth/{batch}:
    get:
      operationId: resolveLogSth
      summary: One batch's signed tree head and its witness co-signatures (GitHub OIDC tokens…
      parameters:
      - name: batch
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: sth
          content:
            application/json:
              examples:
                worked:
                  value:
                    sth:
                      kind: crawlcheck-log-sth
                      v: 1
                      log_id: crawlcheck-resolve-log-v1
                      batch: 12
                      first_index: 5210
                      batch_size: 318
                      tree_size: 5528
                      batch_root: …
                      prev_sth_sha256: …
                      created_at: '2026-10-07T13:02:10.000Z'
                      sha256: …
                      signature: …
                    witnesses:
                    - batch: 12
                      sth_sha256: …
                      witness: github-actions:…
                      token: eyJ…
              schema:
                type:
                - object
                - 'null'
                properties:
                  sth:
                    type:
                    - object
                    - 'null'
                    properties:
                      kind:
                        type:
                        - string
                        - 'null'
                      v:
                        type:
                        - number
                        - 'null'
                      log_id:
                        type:
                        - string
                        - 'null'
                      batch:
                        type:
                        - number
                        - 'null'
                      first_index:
                        type:
                        - number
                        - 'null'
                      batch_size:
                        type:
                        - number
                        - 'null'
                      tree_size:
                        type:
                        - number
                        - 'null'
                      batch_root: {}
                      prev_sth_sha256: {}
                      created_at:
                        type:
                        - string
                        - 'null'
                      sha256: {}
                      signature: {}
                    additionalProperties: true
                  witnesses:
                    type:
                    - array
                    - 'null'
                    items:
                      type:
                      - object
                      - 'null'
                      properties:
                        batch:
                          type:
                          - number
                          - 'null'
                        sth_sha256: {}
                        witness: {}
                        token: {}
                      additionalProperties: true
                additionalProperties: true
                x-schema-source: worked-example
        '404':
          description: no such batch
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s https://crawlcheck.io/api/v1/log/sth/12
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/batch/{batch}:
    get:
      operationId: resolveLogBatch
      summary: One batch's leaf hashes in tree order, so anyone can recompute its root
      parameters:
      - name: batch
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: leaves
          content:
            application/json:
              examples:
                worked:
                  value:
                    batch: 12
                    leaves:
                    - …
              schema:
                type:
                - object
                - 'null'
                properties:
                  batch:
                    type:
                    - number
                    - 'null'
                  leaves:
                    type:
                    - array
                    - 'null'
                    items: {}
                additionalProperties: true
                x-schema-source: worked-example
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s https://crawlcheck.io/api/v1/log/batch/12
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/proof:
    get:
      operationId: resolveLogProof
      summary: 'Inclusion proof for a leaf (?leaf=): batch, index, path and the signed head…'
      parameters:
      - name: leaf
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: proof
          content:
            application/json:
              examples:
                worked:
                  value:
                    leaf_hash: …
                    state: included
                    batch: 12
                    index: 41
                    batch_size: 318
                    path:
                    - …
                    sth:
                      kind: crawlcheck-log-sth
                      v: 1
                      log_id: crawlcheck-resolve-log-v1
                      batch: 12
                      first_index: 5210
                      batch_size: 318
                      tree_size: 5528
                      batch_root: …
                      prev_sth_sha256: …
                      created_at: '2026-10-07T13:02:10.000Z'
                      sha256: …
                      signature: …
              schema:
                type:
                - object
                - 'null'
                properties:
                  leaf_hash: {}
                  state:
                    type:
                    - string
                    - 'null'
                  batch:
                    type:
                    - number
                    - 'null'
                  index:
                    type:
                    - number
                    - 'null'
                  batch_size:
                    type:
                    - number
                    - 'null'
                  path:
                    type:
                    - array
                    - 'null'
                    items: {}
                  sth:
                    type:
                    - object
                    - 'null'
                    properties:
                      kind:
                        type:
                        - string
                        - 'null'
                      v:
                        type:
                        - number
                        - 'null'
                      log_id:
                        type:
                        - string
                        - 'null'
                      batch:
                        type:
                        - number
                        - 'null'
                      first_index:
                        type:
                        - number
                        - 'null'
                      batch_size:
                        type:
                        - number
                        - 'null'
                      tree_size:
                        type:
                        - number
                        - 'null'
                      batch_root: {}
                      prev_sth_sha256: {}
                      created_at:
                        type:
                        - string
                        - 'null'
                      sha256: {}
                      signature: {}
                    additionalProperties: true
                additionalProperties: true
                x-schema-source: worked-example
        '202':
          description: pending
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s 'https://crawlcheck.io/api/v1/log/proof?leaf=<64 hex>'
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/witness/latest:
    get:
      operationId: resolveLogWitnessLatest
      summary: The last head a witness we run on GitHub co-signed, with its token
      responses:
        '200':
          description: witness record
          content:
            application/json:
              examples:
                worked:
                  value:
                    batch: 12
                    sth_sha256: …
                    at: '2026-10-07T13:51:40.000Z'
              schema:
                type:
                - object
                - 'null'
                properties:
                  batch:
                    type:
                    - number
                    - 'null'
                  sth_sha256: {}
                  at:
                    type:
                    - string
                    - 'null'
                additionalProperties: true
                x-schema-source: worked-example
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s https://crawlcheck.io/api/v1/log/witness/latest
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/gossip:
    get:
      operationId: resolveLogGossip
      summary: 'Split-view reports: how many signed tree heads clients have sent, how many…'
      responses:
        '200':
          description: gossip summary
          content:
            application/json:
              examples:
                worked:
                  value:
                    kind: crawlcheck-log-gossip
                    v: 1
                    log_id: crawlcheck-resolve-log-v1
                    reports: 41
                    heads_checked: 388
                    consistent: 388
                    forks: []
                    last_report_at: '2026-10-07T14:02:11.000Z'
              schema:
                type:
                - object
                - 'null'
                properties:
                  kind:
                    type:
                    - string
                    - 'null'
                  v:
                    type:
                    - number
                    - 'null'
                  log_id:
                    type:
                    - string
                    - 'null'
                  reports:
                    type:
                    - number
                    - 'null'
                  heads_checked:
                    type:
                    - number
                    - 'null'
                  consistent:
                    type:
                    - number
                    - 'null'
                  forks:
                    type:
                    - array
                    - 'null'
                    items: {}
                  last_report_at:
                    type:
                    - string
                    - 'null'
                additionalProperties: true
                x-schema-source: worked-example
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s https://crawlcheck.io/api/v1/log/gossip
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    post:
      operationId: resolveLogGossipReport
      summary: 'Send the signed tree heads a client was shown ({sths: [...]}, at most 50).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            examples:
              worked:
                summary: The request behind the worked response
                value:
                  sths:
                  - <signed tree head>
      responses:
        '200':
          description: per-head results
          content:
            application/json:
              examples:
                worked:
                  value:
                    ok: true
                    results:
                    - batch: 12
                      sha256: …
                      state: consistent
                    forks_known: 0
              schema:
                type:
                - object
                - 'null'
                properties:
                  ok:
                    type:
                    - boolean
                    - 'null'
                  results:
                    type:
                    - array
                    - 'null'
                    items:
                      type:
                      - object
                      - 'null'
                      properties:
                        batch:
                          type:
                          - number
                          - 'null'
                        sha256: {}
                        state:
                          type:
                          - string
                          - 'null'
                      additionalProperties: true
                  forks_known:
                    type:
                    - number
                    - 'null'
                additionalProperties: true
                x-schema-source: worked-example
        '400':
          description: no heads
      x-codeSamples:
      - lang: Shell
        label: curl
        source: 'curl -s -X POST https://crawlcheck.io/api/v1/log/gossip -H ''content-type: application/json'' -d ''{"sths":[...]}'''
      security: []
      x-auth: public; no credential read
      x-crawlcheck-budget:
        request_body_max: 1048576
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/gossip/fork/{id}:
    get:
      operationId: resolveLogFork
      summary: One reported fork with both signed heads in full
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: fork evidence
          content:
            application/json:
              examples:
                worked:
                  value:
                    id: 12-0123456789abcdef
                    kind: two_heads_for_one_batch
                    batch: 12
                    ours:
                      sha256: …
                    theirs:
                      sha256: …
                    reported_at: '2026-10-07T14:02:11.000Z'
              schema:
                type:
                - object
                - 'null'
                properties:
                  id:
                    type:
                    - string
                    - 'null'
                  kind:
                    type:
                    - string
                    - 'null'
                  batch:
                    type:
                    - number
                    - 'null'
                  ours:
                    type:
                    - object
                    - 'null'
                    properties:
                      sha256: {}
                    additionalProperties: true
                  theirs:
                    type:
                    - object
                    - 'null'
                    properties:
                      sha256: {}
                    additionalProperties: true
                  reported_at:
                    type:
                    - string
                    - 'null'
                additionalProperties: true
                x-schema-source: worked-example
        '404':
          description: no such fork
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl -s https://crawlcheck.io/api/v1/log/gossip/fork/12-0123456789abcdef
      security: []
      x-auth: public; no credential read
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
  /api/v1/log/witness:
    post:
      operationId: resolveLogWitness
      summary: 'Witness co-signature: a GitHub OIDC token (Authorization: Bearer) from…'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            examples:
              worked:
                summary: The request behind the worked response
                value:
                  batch: 12
                  checked_from: 11
                  checked:
                  - signature
                  - chain
                  - size
                  - root
      responses:
        '200':
          description: recorded
          content:
            application/json:
              examples:
                worked:
                  value:
                    ok: true
                    batch: 12
                    sth_sha256: …
              schema:
                type:
                - object
                - 'null'
                properties:
                  ok:
                    type:
                    - boolean
                    - 'null'
                  batch:
                    type:
                    - number
                    - 'null'
                  sth_sha256: {}
                additionalProperties: true
                x-schema-source: worked-example
        '403':
          description: identity not proven
      x-codeSamples:
      - lang: Shell
        label: curl
        source: (run by .github/workflows/log-witness.yml with its OIDC token)
      security: []
      x-auth: public; no credential read
      x-crawlcheck-budget:
        request_body_max: 1048576
      tags:
      - Log
    servers:
    - url: https://crawlcheck.io
components:
  securitySchemes:
    licenceKey:
      type: apiKey
      in: header
      name: x-crawlcheck-key
      description: 'Your licence key: cc_ followed by 32 hex characters. Sent on every keyed call.'
    bearer:
      type: http
      scheme: bearer
      description: The same licence key as a Bearer token. Accepted on /api/v1/* and /api/usage.
externalDocs:
  url: https://crawlcheck.io/docs/api
  description: Human-readable reference
x-refined-from:
- crawlcheck-io-openapi.json
- crawlcheck-io-openapi.yml