API Evangelist enhancements for the Ocean.io API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Ocean.io API
  version: 1.0.0
extends: openapi/ocean-io-api-openapi.yml
x-generated: '2026-08-13'
x-method: generated
x-source: >-
  Derived from https://api.ocean.io/openapi.json plus Ocean.io's own documentation at
  https://app.ocean.io/docs. Every value below is either a fact restated from the provider's docs or
  an API Evangelist annotation clearly namespaced under x-apievangelist-*. The original harvested
  spec is never mutated — see openapi/_original/ocean-io-openapi.json.
actions:
  - target: $.info
    description: Record provenance and the documentation surface the spec omits.
    update:
      x-apievangelist-source: https://api.ocean.io/openapi.json
      x-apievangelist-harvested: '2026-08-13'
      x-apievangelist-docs: https://app.ocean.io/docs
      x-apievangelist-status-page: https://status.ocean.io/
      x-apievangelist-llms-txt: https://www.ocean.io/llms.txt
      x-apievangelist-mcp-server: https://api.ocean.io/mcp/

  - target: $
    description: >-
      Declare the API-key security scheme the API actually enforces. The published spec declares no
      components.securitySchemes at all, so a generated client will not send authentication; the
      token instead appears as two optional parameters on each operation.
    update:
      components:
        securitySchemes:
          x-apievangelist-ApiTokenHeader:
            type: apiKey
            in: header
            name: X-Api-Token
            description: >-
              Ocean.io account API token, generated at Settings -> API tokens. This is the transport
              Ocean.io recommends, because headers do not appear in server logs or browser history.
          x-apievangelist-ApiTokenQuery:
            type: apiKey
            in: query
            name: apiToken
            description: >-
              The same token as a query parameter. Sending BOTH this and X-Api-Token returns 400
              "Conflicting API tokens provided in query parameters and headers".

  - target: $.info
    description: Record the cross-cutting runtime semantics documented outside the spec.
    update:
      x-apievangelist-conventions:
        pagination:
          style: cursor
          request: searchAfter (body)
          response: searchAfter, total
          terminates_when: searchAfter absent or null
        rate_limits:
          self_serve_per_minute: 60
          self_serve_per_day: 1000
          exhausted_status: 429
          headers:
            - Retry-After
            - X-RateLimit-Limit
          remaining_field: dailyLimitRateLeft (from GET /v2/credits/balance)
        metering:
          model: single shared credit pool
          exhausted_status: 402
          exhausted_behaviour: request not processed, no credits deducted
        idempotency:
          request_key: null
          note: >-
            No idempotency key exists on inbound requests. Ocean.io requires the CONSUMER's webhook
            receiver to be idempotent instead, which shifts replay safety onto the caller.
        error_envelope:
          media_type: application/json
          field: detail
          rfc9457: false

  - target: $.paths['/v2/search/companies'].post
    description: v2 company search is superseded by /v3/search/companies; no sunset date is published.
    update:
      x-apievangelist-superseded-by: searchCompaniesV3
      x-apievangelist-note: >-
        Still live and not marked deprecated by the provider. Ocean.io publishes no deprecation
        policy or Sunset header, so consumers have no signal about its lifetime.

  - target: $.paths['/v2/search/people'].post
    description: v2 people search is superseded by /v3/search/people; no sunset date is published.
    update:
      x-apievangelist-superseded-by: searchPeopleV3
      x-apievangelist-note: >-
        Still live and not marked deprecated by the provider.

  - target: $.paths['/v2/reveal/emails'].post
    description: Annotate the asynchronous callback contract and its billing consequence.
    update:
      x-apievangelist-async:
        pattern: webhook-callback
        request_field: webhookUrl
        ack: '{"status": "in progress"}'
        webhook_event: reveal_emails
        typical_latency: 1-10 minutes depending on batch size
        billing: 1 credit per email found; notFound is not charged
        replay_risk: >-
          No request-side idempotency key. A retried submission can be charged twice; deduplicate on
          personId in the receiver.

  - target: $.paths['/v2/reveal/phones'].post
    description: Annotate the asynchronous callback contract.
    update:
      x-apievangelist-async:
        pattern: webhook-callback
        request_field: webhookUrl
        webhook_event: reveal_phones
        billing: 10 credits per phone found; notFound is not charged

  - target: $.paths['/v2/enrich/companies'].post
    description: Annotate the batch callback contract and the reconciliation key.
    update:
      x-apievangelist-async:
        pattern: webhook-callback
        request_field: webhookUrl
        webhook_event: enrich_companies
        correlation_key: the caller's own keys in companyDataMapping are echoed in the webhook payload
        batch_max: 10000
        result_statuses:
          - found
          - not_found
          - triggered

  - target: $.paths['/v2/enrich/people'].post
    description: Annotate the batch callback contract.
    update:
      x-apievangelist-async:
        pattern: webhook-callback
        request_field: webhookUrl
        webhook_event: enrich_people
        correlation_key: the caller's own keys in peopleDataMapping are echoed in the webhook payload
        batch_max: 10000

  - target: $.paths['/v2/warmup/companies'].post
    description: Flag the free pre-flight operation that avoids wasted enrichment credits.
    update:
      x-apievangelist-cost: free
      x-apievangelist-note: >-
        Call before a batch enrichment. Splits input into successfulDomains (indexed) and
        triggeredDomains (crawling started, retry in 2-5 minutes).

  - target: $.paths['/v2/lookup/companies'].post
    description: Flag the cheaper alternative to search when the domains are already known.
    update:
      x-apievangelist-cost: 0.05 credits per result
      x-apievangelist-note: Cheaper than searchCompaniesV3 with includeDomains (0.2 credits per result).

  - target: $.paths['/v2/data-fields'].get
    description: Flag the enum authority for every filter value in the API.
    update:
      x-apievangelist-cost: free
      x-apievangelist-note: >-
        Authoritative source for industry, technology and field enum values. Any filter value that
        does not match here returns 422.