sweeps

Submit an async global CN/SAN sweep

Submit a global (domain-less) attribution sweep as an async job.

Use this instead of /v1/certificates/search when a cn / san_contains sweep needs to go deeper than the synchronous result cap or would exceed the synchronous query budget. Consumes one global_sweep_per_hr quota unit at submit; polling is free.

The attribution knobs (strict_attribution, exclude_subject_o, registrable_domain_denylist) are post-match filters applied after the candidate scan — they do not reduce scan cost and cannot prevent sweep_timeout. To bound scan cost on a broad token, narrow cn / san_contains or add issuer / first_seen_* / not_after_* windows.

Continuation past the result cap: when a finished sweep reports truncated: true, its status response carries a next_cursor token. Submit a NEW sweep with the SAME filters plus resume_token: <next_cursor> to fetch the next chunk of up to result_cap rows — keyset semantics, so no rows are skipped or duplicated across the boundary. Repeat until truncated is false. Example: sweep 1 ({"cn": "acme"}) → done, truncated, next_cursor "eyJ2IjoxLC…" → sweep 2 ({"cn": "acme", "resume_token": "eyJ2IjoxLC…"}) → next 10 000 rows. Each continuation consumes one quota unit.

post/v1/sweeps

Request

  • Base URL: https://api.ctindex.io
  • URL: https://api.ctindex.io/v1/sweeps
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Cookies

ctix_sessionstring nullable

Request body

cnstring nullable

Subject CN ILIKE substring (3+ chars)

issuerstring nullable

Issuer substring, matched against issuer CN and issuer organization. Only allowed composed with cn/san_contains.

san_containsstring nullable

SAN substring match across all names (3+ chars)

is_wildcardboolean nullable
is_precertboolean nullable
expiredboolean nullable

true = expired only; false = currently valid only

first_seen_afterstring nullable

ISO-8601

first_seen_beforestring nullable

ISO-8601

not_after_afterstring nullable

ISO-8601

not_after_beforestring nullable

ISO-8601

strict_attributionboolean nullable

true = drop 'substring_collision', 'shared_hosting', and 'third_party_integration' rows from the persisted result set — these classes indicate legitimate third-party use, not brand abuse. 'first_party' and 'lookalike_candidate' rows are always retained. Default false. Post-match filter: applied after the candidate scan — does not reduce scan cost or prevent sweep_timeout.

exclude_subject_ostring[] nullable

Exclude rows whose subject organization contains any of these substrings (case-insensitive), e.g. ["ADIDAS AG"]. Rows with no subject_o are kept. Max 20 entries. Post-match filter: applied after the candidate scan — does not reduce scan cost or prevent sweep_timeout.

registrable_domain_denyliststring[] nullable

Exclude rows whose subject CN is, or is under, any of these registrable domains (eTLD+1 suffix match), e.g. ["silverstripe.com", "amazonaws.com"]. Max 20 entries. Post-match filter: applied after the candidate scan — does not reduce scan cost or prevent sweep_timeout.

resume_tokenstring nullable

Keyset continuation token (task #856). Pass the exact next_cursor value from a previous sweep result that had truncated: true (same filters!) to resume the sweep strictly after the last returned row. Continuation is deterministic — the result set is materialized under a stable total order (first_seen DESC, sha256 DESC), so pages never skip or duplicate rows across the boundary. Each continuation is a new sweep submission and consumes one global_sweep_per_hr quota unit. Do not construct this value yourself.

first_party_domainsstring[] nullable

The sweep target's OWN registrable domain(s), e.g. ["datadoghq.com", "datadoghq.eu"]. Any result name on one of these registrable domains is classed match_class = 'first_party' regardless of the certificate's subject organization — use this when the brand's domain does not contain the token as a whole label (datadog → datadoghq.com). Supplying this list makes it AUTHORITATIVE: a name on any OTHER registrable domain is no longer inferred first-party from the hostname alone, so a squat whose domain happens to carry the search token as a label (datadog.now, datadog.co.uk) stays visible as 'lookalike_candidate' instead of being filed as first-party. The brand's own certificates on domains you did not list still class 'first_party' when their subject organization proves it (match_reason 'subject_org_match;...' / 'first_party_org_match;...'); allowlist hits read 'first_party_allowlist;rd=...'. Classification-side only (does not filter the result set). Max 20 entries.

match_class_filterstring nullable

Optional comma-separated attribution classes to retain in polling results. Allowed values: first_party, lookalike_candidate, third_party_integration, substring_collision, shared_hosting. Values are normalized, de-duplicated, and persisted with the sweep.

Response

Successful Response

job_idstring uuid required
statusstring required
result_capinteger required
poll_urlstring required
messagestring required

Changes

No recorded changes to this operation across all 1 revision of this API.