API reference

Authentication

API tokens are issued at the workspace level by an owner or admin from /settings/api-tokens. Tokens carry one or more scopes and authenticate on every request via the Authorization: Bearer <token> header.

A request to an endpoint your token does not have the scope for returns 403. Verify your token and active scopes with GET /api/v1/me.

Endpoints

List endpoints use cursor-based pagination at 100 records per page. Follow next_page_url from the response envelope until it returns null.

Entity lookup

The core enrichment endpoint. Pass a domain and receive a dossier of disclosed observations. Call it from anywhere — a Clay column, an Apollo workflow, a Python backfill script, a Zapier trigger, a CRM webhook, your own scheduled job. Returns {"entity": null} if no match; returns {"entity": null, "reason": "opt_out"} if the entity has opted out (DNS TXT ciphercue-optout=true or written request).

curl -H "Authorization: Bearer $CIPHERCUE_TOKEN" \
  "https://ciphercue.com/api/v1/entities/lookup?domain=example.com"

Response shape (truncated for readability):

{
  "entity": {
    "id": "01HXY…",
    "canonical_name": "Example Corp",
    "website": "example.com",
    "apex_domain": "example.com",
    "entity_type": "company",
    "industry": "Manufacturing",
    "country": "US",
    "enriched_at": "2026-06-09T22:14:11+00:00",
    "facts": {
      "kev_matches": [{
        "cve_id": "CVE-2024-1234",
        "vendor": "Acme",
        "product": "Widget",
        "detected_version": "3.2.1",
        "first_seen_at": "2026-05-12T09:00:00+00:00",
        "source_quote": "Acme Widget contains an authentication bypass…",
        "source_attribution": "CISA Known Exploited Vulnerabilities Catalog",
        "primary_sources": [
          { "label": "CISA KEV entry", "identifier": "CVE-2024-1234",
            "url": "https://www.cisa.gov/known-exploited-vulnerabilities-catalog" },
          { "label": "NVD CVE record", "identifier": "CVE-2024-1234",
            "url": "https://nvd.nist.gov/vuln/detail/CVE-2024-1234" }
        ]
      }],
      "tech_stack": [ /* … */ ],
      "dns_compliance": { "spf": "…", "dkim": "…", "dmarc": "…", "primary_sources": [ /* … */ ] },
      "cert_transparency": [ /* … */ ]
    },
    "watchlist": { "is_tracked": true, "signal_count": 4 }
  }
}

Facts and change events

The lookup endpoint returns a curated dossier. /entities/{id}/facts returns the raw fact records, filterable by type (e.g. kev_match, tech_fingerprint, dns_compliance, cert_transparency, tls_certificate, trust_page) and since timestamp. /entities/{id}/changes returns the diffed change events the dashboard renders: tech stack additions, email policy changes, new services, certificate issuer changes, KEV match additions.

Both endpoints filter out pre-disclosure facts inside the 48-hour silent window. This is the same gate the application UI applies; the API never bypasses it.

Signals

/signals returns your workspace's own signal queue. Filter by since, status (new, open, closed, duplicate), and severity (critical, high, medium, low). Signal records carry the source's original disclosure URL under primary_sources.

Accounts

/accounts returns your workspace's tracked entities (your account list). Use this to seed external systems with your CipherCue watchlist — populating a Clay table, an Apollo list, a CRM segment, or any downstream pipeline.

Rate limits and quotas

Two independent limits:

• Burst: 60 requests per minute per token. Headers: X-RateLimit-Limit, X-RateLimit-Remaining.
• Monthly: per workspace. Free workspaces get 1,000 calls per month for trialing GTM wiring; paid workspaces get 100,000 (contact us for higher limits). Headers: X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset.

Both limits return 429 Too Many Requests when exceeded. Schedule retries against the X-Quota-Reset ISO timestamp — most HTTP clients (Clay, Apollo, Zapier, etc.) surface the response headers automatically.

Legal posture

Every API response that contains an observation about a third-party entity follows the same posture as the CipherCue UI:

• Negative assertions carry primary_sources linking to the original public record we observed.
• Third-party-sourced text (e.g. CISA descriptions) is wrapped as source_quote with source_attribution. CipherCue authors no judgement vocabulary in those fields.
• Observations within the 48-hour silent disclosure window are never returned. The gate is applied at the database query, not in serialisation.
• Opted-out entities return {"entity": null, "reason": "opt_out"}. Opt-out is honoured within 7 days via DNS TXT ciphercue-optout=true or email to abuse@ciphercue.com.

See the public disclosure policy and opt-out pages for the methodology.

Integration recipes

The endpoints above are general-purpose. These pages walk through wiring them into specific tools:

• Clay HTTP Enrichment recipe — /entities/lookup as a Clay column.
• Apollo HTTP enrichment recipe — workflow + CSV-loop patterns.

If you've wired CipherCue into another tool (Zapier, Make, n8n, your CRM's native webhook, a custom service) and want it documented here, email support@ciphercue.com.