API Evangelist overlay for the 2s OpenAPI

overlay: 1.0.0
info:
  title: API Evangelist overlay for the 2s OpenAPI
  version: '2026-09-19'
  description: 'Enhancements API Evangelist derived while profiling 2s on 2026-09-19: tag declarations from the
    provider''s catalog.txt, the error envelope observed live, the 429/503 throttle responses documented in the
    provider''s changelog, discovery-document cross-links, and idempotency/reversibility markers quoted from operation
    descriptions. The original spec is never mutated; apply this overlay to openapi/2s-io-openapi.json.'
extends: openapi/2s-io-openapi.json
x-generated: '2026-09-19'
x-method: generated
x-source:
- https://2s.io/openapi.json
- https://2s.io/catalog.txt
- https://2s.io/changelog.json
- https://2s.io/.well-known/2s-attestation.json
- GET https://2s.io/api/validate/iban?trial=1 (observed 400)
actions:
- target: $.info
  update:
    termsOfService: null
    x-apievangelist-note: No terms of service or privacy policy page exists on 2s.io (all conventional paths 404,
      2026-09-19); the status page carries the only published commitments.
- target: $.info
  description: Name the discovery documents the provider publishes but the spec does not reference
  update:
    x-discovery:
      apisJson: https://2s.io/apis.json
      apiCatalog: https://2s.io/.well-known/api-catalog
      llmsTxt: https://2s.io/llms.txt
      mcp: https://2s.io/mcp
      mcpServerCard: https://2s.io/.well-known/mcp/server-card.json
      a2aAgentCard: https://2s.io/.well-known/agent-card.json
      x402Manifest: https://2s.io/.well-known/x402
      status: https://2s.io/status.json
      changelog: https://2s.io/changelog.json
      attestation: https://2s.io/.well-known/2s-attestation.json
- target: $
  description: Declare the 112 tags the operations already use, with the provider's own group descriptions from
    https://2s.io/catalog.txt
  update:
    tags:
    - name: agent
      description: Agent-native knowledge-delta primitive
    - name: agriculture
      description: Drought monitor & USDA stats
    - name: ai
      description: Summarize, translate, extract, screenshot & describe
    - name: airport
      description: Airport lookup & nearest airports
    - name: aviation
      description: METAR, TAF, SIGMET & accident records
    - name: bank
      description: Bank routing lookup
    - name: barcode
      description: Barcode generation
    - name: batch
      description: Run many endpoints in one settled call
    - name: bio
      description: Species, genes & proteins
    - name: bls
      description: BLS time-series data
    - name: book
      description: Book search
    - name: business
      description: Company registries, LEI, KYB & entity screening
    - name: calendar
      description: Business days, holidays, earnings & IPO calendars
    - name: census
      description: ACS demographics & ZIP geographies
    - name: chem
      description: Chemical compound data
    - name: chinese
      description: Chinese data & lookups
    - name: class
      description: Class data & lookups
    - name: climate
      description: Station history & nearest stations
    - name: clinical
      description: ClinicalTrials search & study detail
    - name: code
      description: Repo lookup & code tools
    - name: convert
      description: Currency & unit conversion
    - name: countdown
      description: Countdown GIF generator
    - name: country
      description: Country reference data
    - name: crypto
      description: Prices, gas, fees, DeFi, contracts & on-chain data
    - name: dev
      description: RFC lookup & deploy preflight
    - name: dns
      description: DNS record lookup
    - name: domain
      description: WHOIS, intel, CT logs & email security
    - name: earth
      description: Natural events & planetary now
    - name: econ
      description: FRED series, releases, vintages, yield curve & indicators
    - name: edi
      description: Parse, generate & acknowledge X12 / EDIFACT
    - name: edu
      description: College Scorecard & school lookup
    - name: email
      description: Email address validation
    - name: energy
      description: Prices, generation mix, utility rates & solar resource
    - name: factcheck
      description: Fact-check claim search
    - name: feedback
      description: Send a message to the 2s team
    - name: finance
      description: SEC EDGAR filings, 13F, company facts & FIGI
    - name: flight
      description: Live flight status
    - name: food
      description: UK hygiene ratings & barcode lookup
    - name: fx
      description: Foreign-exchange rates & time series
    - name: geo
      description: Geocoding, elevation, flood zones, IP & dossiers
    - name: geocode
      description: Address ↔ coordinate, forward & reverse
    - name: github
      description: Repos, users, commits, issues, PRs & code search
    - name: gov
      description: 'Federal data: Congress, FEC, FDA, SAM, FEMA & more'
    - name: hash
      description: Hash computation
    - name: health
      description: Hospitals, providers, Medicare, mortality & surveillance
    - name: html
      description: HTML → Markdown conversion
    - name: image
      description: Image compression
    - name: inflation
      description: CPI calculator, rates, expectations & HICP
    - name: ipinfo
      description: Bulk IP geolocation
    - name: iso
      description: ISO currency, language & subdivision codes
    - name: job
      description: Federal job search & occupation codes
    - name: labor
      description: BLS openings, unemployment & wages
    - name: law
      description: OFAC sanctions, case law & dockets
    - name: license
      description: Verify broker, medical, real-estate & trade licenses
    - name: lock
      description: Distributed locks/leases — one agent at a time
    - name: maritime
      description: Vessels, ports & maritime case records
    - name: markets
      description: Exchange open/closed status & market holidays
    - name: medical
      description: ICD-10, NPI, drug labels, approvals & device data
    - name: music
      description: MusicBrainz artists, releases & recordings
    - name: net
      description: ASN / BGP, MAC vendor & RPKI validity
    - name: news
      description: Hacker News items, top stories & web news search
    - name: nonprofit
      description: Nonprofit search & screening
    - name: nutrition
      description: Food & nutrition facts
    - name: occupation
      description: O*NET occupation profiles, search & relations
    - name: paper
      description: DOI metadata lookup
    - name: papers
      description: Academic paper search & citation graphs (arXiv, OpenAlex & more)
    - name: park
      description: US National Park lookup
    - name: patents
      description: USPTO patent search, detail & documents
    - name: person
      description: Cross-registry person lookup
    - name: phone
      description: Phone number normalization
    - name: poi
      description: Points of interest nearby
    - name: predict
      description: Polymarket prediction markets, prices, trades & whales
    - name: product
      description: GTIN / UPC / EAN identity
    - name: property
      description: NYC deeds, parcels, permits & violations
    - name: pubsub
      description: Topics + fan-out signed callbacks for agent coordination
    - name: quakes
      description: Recent earthquakes (USGS)
    - name: queue
      description: 'Durable task queues: enqueue, lease, ack, dead-letter'
    - name: recreation
      description: Recreation.gov facility search
    - name: registry
      description: npm & PyPI package lookups
    - name: research
      description: ORCID authors, ROR orgs & NIH funding
    - name: schedule
      description: Time-driven signed callbacks — cron for agents
    - name: search
      description: Endpoint discovery & web search
    - name: security
      description: CVEs, KEV, EPSS, IOC reputation, headers, exposure
    - name: soil
      description: Soil profiles & USDA hardiness zones
    - name: space
      description: Launches, satellites, exoplanets, sky & space weather
    - name: sports
      description: MLB & NHL schedules, scores & standings
    - name: stocks
      description: Quotes, metrics, analyst, earnings, news, gov/alt data
    - name: store
      description: 'Wallet-keyed persistence: KV, documents, vector search & private files'
    - name: sunrise
      description: Sunrise / sunset times
    - name: tax
      description: VAT validation & EU VAT-rate tables
    - name: tcg
      description: Tcg data & lookups
    - name: telecom
      description: FCC filings & telecom market areas
    - name: text
      description: Text data & lookups
    - name: tides
      description: Current tide predictions
    - name: time
      description: Time data & lookups
    - name: timezone
      description: Timezone by coordinate
    - name: tld
      description: Top-level-domain info
    - name: tls
      description: TLS certificate inspection
    - name: trade
      description: UN Comtrade flows, tariffs & LOCODE
    - name: transcribe
      description: Audio transcription
    - name: travel
      description: Travel advisories & visa requirements
    - name: treasury
      description: US Treasury cash, debt, rates & monthly statements
    - name: url
      description: Render, map, clean & unfurl any URL
    - name: validate
      description: IBAN, BIC, ISIN, CUSIP, GTIN & check-digit checks
    - name: vehicle
      description: VIN decode, recalls, complaints, safety ratings
    - name: watchers
      description: Watchers data & lookups
    - name: water
      description: USGS stream-gauge readings
    - name: weather
      description: Global conditions & forecasts, NWS alerts, marine & air quality
    - name: wikidata
      description: Wikidata entity lookup
    - name: wikipedia
      description: Wikipedia article summaries
    - name: word
      description: Definitions & related words
    - name: worldbank
      description: World Bank development indicators
- target: $
  update:
    externalDocs:
      description: 2s llms.txt — payment flow, discovery surfaces, SDKs and the full endpoint list
      url: https://2s.io/llms.txt
- target: $.servers[0]
  update:
    description: Single production origin; also hosts the MCP server (/mcp) and the A2A JSON-RPC endpoint (/a2a).
      No sandbox host — use ?trial=1 for a free real call.
- target: $.components.responses
  description: Add the two throttle responses the provider documents in changelog 1.80.1 but does not declare
  update:
    RateLimited:
      description: 429 RATE_LIMITED — 2s's own rate limiter (changelog 1.80.1). Back off client-side. No Retry-After
        header is documented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    UpstreamRateLimit:
      description: 503 UPSTREAM_RATE_LIMIT — an upstream throttle, not the caller's limit; the provider says retry
        without client-side backoff (changelog 1.80.1).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
- target: $.components.schemas
  description: Declare the error envelope observed live on a trial 400 (2026-09-19)
  update:
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: UPPER_SNAKE code — BAD_REQUEST, RATE_LIMITED, UPSTREAM_RATE_LIMIT, RESULT_TOO_LARGE,
                NOT_FOUND observed or documented
              example: BAD_REQUEST
            message:
              type: string
              example: Invalid parameters.
            details:
              type: object
              description: Optional; on 400 a validation report with issues[] {code, expected, received, path[],
                message}
- target: $.components.responses.BadRequest
  update:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorEnvelope'
        example:
          error:
            code: BAD_REQUEST
            message: Invalid parameters.
            details:
              issues:
              - code: invalid_type
                expected: string
                received: undefined
                path:
                - iban
                message: Required
- target: $.paths.*[?(@.operationId)]
  description: Wire the two documented throttle responses onto every operation
  update:
    responses:
      '429':
        $ref: '#/components/responses/RateLimited'
      '503':
        $ref: '#/components/responses/UpstreamRateLimit'
- target: $.paths.*[?(@.operationId)]
  description: Name the headers the provider documents on a paid 200 and on a signed response
  update:
    x-response-headers:
      X-PAYMENT-TX: on-chain settlement transaction of the x402 payment
      X-2s-Endpoint: endpoint id (attestation descriptor)
      X-2s-Attestation-Signature: present when ?sign=1 — EIP-191 signature over the canonical message; see https://2s.io/.well-known/2s-attestation.json
- target: $.paths['/api/lock/release'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/watchers/cancel'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/pubsub/create-topic'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/store/kv-delete'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/store/doc-delete'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/store/vector-delete'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/store/blob-delete'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/text/redact'].post
  update:
    x-idempotent: true
    x-idempotency-basis: stated in the operation description
- target: $.paths['/api/watchers/cancel'].post
  update:
    x-reversal-of: watchers.* arming operations
    x-refund: none — the contract states no refund of the unused window
- target: $.paths['/api/schedule/cancel'].post
  update:
    x-reversal-of: schedule.create
    x-refund: none — the contract states no refund of the unused window
- target: $.paths['/api/lock/release'].post
  update:
    x-reversal-of: lock.acquire
    x-refund: null
- target: $.paths['/api/pubsub/unsubscribe'].post
  update:
    x-reversal-of: pubsub.subscribe
    x-refund: null
- target: $.paths['/api/queue/ack'].post
  update:
    x-reversal-of: queue.lease (makes the removal permanent)
    x-refund: null
- target: $.paths['/api/store/kv-delete'].post
  update:
    x-reversal-of: store.kv-put
    x-restore: none documented; objects also expire 90 days after last touch
- target: $.paths['/api/store/doc-delete'].post
  update:
    x-reversal-of: store.doc-put
    x-restore: none documented; objects also expire 90 days after last touch
- target: $.paths['/api/store/vector-delete'].post
  update:
    x-reversal-of: store.vector-upsert
    x-restore: none documented; objects also expire 90 days after last touch
- target: $.paths['/api/store/blob-delete'].post
  update:
    x-reversal-of: store.blob-put
    x-restore: none documented; objects also expire 90 days after last touch