overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Coresignal Collect API
  version: 1.0.0
extends: openapi/coresignal-collect-api-openapi.yml
x-generated: '2026-08-13'
x-method: generated
x-source: >-
  Derived from artifacts in this repo: conventions/coresignal-conventions.yml,
  errors/coresignal-error-codes.yml, plans/coresignal-plans-pricing.yml,
  data-model/coresignal-data-model.yml. Captures API Evangelist annotations only; the underlying spec
  is never mutated.
actions:
  - target: $.info
    update:
      x-apievangelist-slug: coresignal
      x-apievangelist-artifacts:
        conventions: conventions/coresignal-conventions.yml
        errors: errors/coresignal-error-codes.yml
        plans: plans/coresignal-plans-pricing.yml
        data_model: data-model/coresignal-data-model.yml
        mcp: mcp/coresignal-mcp.yml
      x-metering:
        unit: credit
        remaining_header: x-credits-remaining
        exhaustion_status: 402
        note: Credits are deducted on each successful (200) collect. Search is free.
  - target: $.components.securitySchemes.apiKey
    update:
      description: >-
        32-character alphanumeric API key issued in the Coresignal dashboard, sent in the `apikey`
        request header. No scopes.
      x-key-format: 32-character alphanumeric
      x-issuer: https://dashboard.coresignal.com/
  - target: $.paths['/collect/{id}'].get
    update:
      x-credit-cost: 20
      x-credit-cost-note: >-
        Multi-source Company / Employee records cost 20 credits each; Base and Clean cost 10; Jobs and
        Posts cost 1. Source: https://docs.coresignal.com/pricing/pricing
      x-404-semantics: >-
        404 is overloaded — it means either a nonexistent API URL or a record id absent from the
        database. Check the path before treating it as a data miss.
  - target: $.paths['/bulk_collect'].post
    update:
      x-async: true
      x-max-ids: 10000
      x-retrieval-window-days: 30
      x-duplicate-detection:
        status: 409
        body: '{"detail": "Identical data request is already in progress."}'
        note: >-
          Server-side de-duplication of identical in-flight submissions. This is NOT a client-supplied
          idempotency key — the caller cannot name or replay a request.
      x-credit-cost-note: One credit unit per record collected, at the per-record rate for the dataset.
  - target: $.paths['/bulk_collect'].post.responses
    update:
      '201':
        description: Bulk job accepted.
      '202':
        description: The bulk process is in progress; poll the job.
      '409':
        description: >-
          Duplicate POST — an identical data request is already in progress. Poll the existing job
          rather than resubmitting.
      '422':
        description: >-
          Request exceeded the 10,000 ID limit, contained duplicates, or the provided URLs cannot be
          parsed into shorthand names.