CTlogs.io Certs API

openapi: 3.2.0
info:
  title: Ctlogs Io Certs API
  version: 1.0.0
  contact:
    url: https://ctlogs.io/docs
  description: 'Operations tagged Certs across 2 of this provider''s published API definitions: ctlogs-io-openapi.json, ctlogs-io-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ctlogs.io
security:
- ApiKeyHeader: []
tags:
- name: Certs
paths:
  /v1/certs:
    get:
      operationId: listCertificates
      summary: Certificate records for a hostname, a registered domain or a fingerprint
      description: Exactly one of domain, reg_domain or fingerprint identifies what to look up. reg_domain and include_subdomains deduplicate by fingerprint and return the newest log entry's values.
      parameters:
      - name: domain
        in: query
        schema:
          type: string
        description: exact hostname
      - name: reg_domain
        in: query
        schema:
          type: string
        description: registered domain; the root and everything under it
      - name: fingerprint
        in: query
        schema:
          type: string
        description: SHA-256, 64 hex characters; colons and spaces accepted
      - name: include_subdomains
        in: query
        schema:
          type: string
          enum:
          - 'true'
        description: widens domain to that name and everything under it; 400 with fingerprint
      - name: issuer
        in: query
        schema:
          type: string
        description: exact match on the issuer string
      - name: cert_type
        in: query
        schema:
          type: string
          enum:
          - DV
          - OV
          - EV
          - unknown
      - $ref: '#/components/parameters/scope'
      - $ref: '#/components/parameters/after'
      - $ref: '#/components/parameters/before'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: missing or contradictory parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/Unavailable'
      tags:
      - Certs
    servers:
    - url: https://api.ctlogs.io
components:
  responses:
    MethodNotAllowed:
      description: every endpoint is read-only; only GET and HEAD are answered
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: missing, unknown or revoked key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: hourly bucket spent, or too many in flight
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: prepaid credits are used up; buying another pack restores access, and retrying does not
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: the index could not be reached; this is not the same as no results
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    scope:
      name: scope
      in: query
      required: false
      schema:
        type: string
        enum:
        - valid
        - all
        default: valid
      description: valid reads certificates with not_after on or after 2026-07-01; all reaches back to not_after 2025-01-01. Any other value behaves as valid.
    after:
      name: after
      in: query
      required: false
      schema:
        type: string
      description: log_time >= after, inclusive. YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.
    before:
      name: before
      in: query
      required: false
      schema:
        type: string
      description: log_time <= before, inclusive.
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
      description: rows per page; clamped to the plan's page size.
  schemas:
    Envelope:
      type: object
      required:
      - status
      - count
      - data
      properties:
        status:
          type: string
          const: ok
        count:
          type: integer
          description: rows in data on this page
        elapsed:
          type: string
          description: server-side time, Go duration format
        next_cursor:
          type: string
          description: present only when another page exists
        data:
          type: array
          items:
            type: object
    Error:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          const: error
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: A ?key= query parameter is also accepted but writes the key into proxy logs and Referer headers. Plain HTTP is refused, not redirected.
x-refined-from:
- ctlogs-io-openapi.json
- ctlogs-io-openapi.yml