CTlogs.io Search API

openapi: 3.2.0
info:
  title: Ctlogs Io Search API
  version: 1.0.0
  contact:
    url: https://ctlogs.io/docs
  description: 'Operations tagged Search 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: Search
paths:
  /v1/search:
    get:
      operationId: searchHostnames
      summary: Substring match anywhere in a hostname
      description: 'Matches the whole hostname string, so a query for one brand also finds it inside an unrelated registered domain. Runs under a wall-clock budget: a rare term can return a truncated answer rather than wait.'
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      - name: field
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: tld
        in: query
        schema:
          type: string
      - name: issuer
        in: query
        schema:
          type: 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 too short a query
          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:
      - Search
    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