openapi: 3.2.0
info:
  title: 2s — the (most) everything Papers API
  version: '1'
  summary: The (most) everything API.
  description: 'The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin.'
  contact:
    name: 2s
    url: https://2s.io
    email: alley@2s.io
  x-logo:
    url: https://2s.io/icon-512.png
    altText: 2s
  x-guidance: 'Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q=<natural-language task> for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run.'
servers:
- url: https://2s.io
tags:
- name: Papers
paths:
  /api/papers/citations:
    get:
      tags:
      - Papers
      summary: Citation graph for a scholarly work via OpenAlex
      description: Citation graph for a scholarly work via OpenAlex. Pass id as a DOI (10.xxxx/…, doi.org URL) or an OpenAlex work id (W…). Returns the work's total citation count + reference count, and a paginated list of either the works that CITE it (view=citing, default — sort=recent for newest-first or sort=citations for most-cited-first) or the works it REFERENCES (view=referenced). Each listed work gives DOI, title, year, venue, authors, and its own citation count. Fresh citation data lands after any training cutoff. Complements papers.search (finding papers) with graph traversal (following citations).
      operationId: papers_citations
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = citing or referenced works (id, doi, title, year, venue, authors, citedByCount); total = full count for the selected view; meta.work = the queried work summary (citedByCount + referencedCount).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: OpenAlex work id (short form, e.g. W3177828909).
                            doi:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            year:
                              type: number
                              nullable: true
                            publishedAt:
                              type: string
                              nullable: true
                            citedByCount:
                              type: number
                              nullable: true
                            authors:
                              type: array
                              items:
                                type: string
                              description: Author display names (first 10).
                            authorCount:
                              type: number
                            venue:
                              type: string
                              nullable: true
                            url:
                              type: string
                              nullable: true
                          required:
                          - id
                          - doi
                          - title
                          - year
                          - publishedAt
                          - citedByCount
                          - authors
                          - authorCount
                          - venue
                          - url
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      page:
                        type: object
                        properties:
                          number:
                            type: integer
                          size:
                            type: integer
                          pages:
                            type: integer
                            nullable: true
                        required:
                        - number
                        - size
                        - pages
                        additionalProperties: false
                      meta:
                        type: object
                        properties:
                          view:
                            type: string
                          work:
                            type: object
                            properties:
                              id:
                                type: string
                              doi:
                                type: string
                                nullable: true
                              title:
                                type: string
                                nullable: true
                              year:
                                type: number
                                nullable: true
                              citedByCount:
                                type: number
                              referencedCount:
                                type: number
                            required:
                            - id
                            - doi
                            - title
                            - year
                            - citedByCount
                            - referencedCount
                            additionalProperties: false
                        required:
                        - view
                        - work
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: papers.citations
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: query
        required: true
        description: DOI or OpenAlex work id.
        schema:
          type: string
          minLength: 4
          maxLength: 500
      - name: view
        in: query
        required: false
        description: View.
        schema:
          type: string
          enum:
          - citing
          - referenced
          default: citing
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 1
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - recent
          - citations
          default: recent
      - $ref: '#/components/parameters/TrialMode'
  /api/papers/search:
    get:
      tags:
      - Papers
      summary: Unified scientific literature search across arXiv
      description: 'Unified scientific literature search across arXiv (preprints), PubMed (biomedical), and Semantic Scholar (cross-field, with citation counts). Returns a flat array of papers with stable schema: source, sourceId, doi, title, authors, abstract, year, publishedAt, citationCount, url, pdfUrl. Partial failures surface in the errors array rather than failing the whole call. Optional filters: since (YYYY-MM-DD), sources (subset), limit (max 20 per source).'
      operationId: papers_search
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = papers (flat array across arXiv + PubMed + Semantic Scholar; source, sourceId, doi, title, authors, abstract, year, citationCount, url, pdfUrl); total = count returned across sources; meta.errors = degraded sources; meta.sources/attribution describe per-source coverage.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            source:
                              type: string
                              enum:
                              - arxiv
                              - pubmed
                              - semantic-scholar
                            sourceId:
                              type: string
                              description: Source-native stable id (arXiv id, PMID, S2 paperId).
                            doi:
                              type: string
                              nullable: true
                            title:
                              type: string
                            authors:
                              type: array
                              items:
                                type: string
                            abstract:
                              type: string
                              nullable: true
                            year:
                              type: number
                              nullable: true
                            publishedAt:
                              type: string
                              nullable: true
                              description: ISO 8601 timestamp when the source provides a full date.
                            citationCount:
                              type: number
                              nullable: true
                              description: From Semantic Scholar; null for arXiv/PubMed results.
                            url:
                              type: string
                              description: Canonical URL to view the paper.
                            pdfUrl:
                              type: string
                              nullable: true
                              description: Direct PDF when available (mostly arXiv).
                          required:
                          - source
                          - sourceId
                          - doi
                          - title
                          - authors
                          - abstract
                          - year
                          - publishedAt
                          - citationCount
                          - url
                          - pdfUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: string
                            description: Echo of the free-text query.
                          sources:
                            type: array
                            items:
                              type: string
                            description: Sources actually queried (after filtering).
                          errors:
                            type: array
                            items:
                              type: object
                              properties:
                                source:
                                  type: string
                                message:
                                  type: string
                              required:
                              - source
                              - message
                              additionalProperties: false
                            description: Per-source failures; empty when all sources succeeded.
                          attribution:
                            type: array
                            items:
                              type: object
                              properties:
                                source:
                                  type: string
                                license:
                                  type: string
                                url:
                                  type: string
                              required:
                              - source
                              - license
                              - url
                              additionalProperties: false
                            description: Per-source license + terms.
                        required:
                        - query
                        - sources
                        - errors
                        - attribution
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: papers.search
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: q
        in: query
        required: true
        description: Free-text search query.
        schema:
          type: string
          minLength: 1
          maxLength: 500
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 10
      - name: since
        in: query
        required: false
        description: Since.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: sources
        in: query
        required: false
        description: Sources.
        schema:
          type: string
      - $ref: '#/components/parameters/TrialMode'
components:
  schemas:
    Source:
      type: object
      description: 'Provenance of the data: upstream provider, source URL, and license.'
      properties:
        provider:
          type: string
          description: Upstream data provider.
        url:
          type: string
          description: Source URL or documentation link.
        license:
          type: string
          description: License / usage terms for the data.
    CallMeta:
      type: object
      description: Per-call meta envelope — endpoint id, cost, caller kind, settlement details.
    X402PaymentRequiredV2:
      type: object
      description: x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header.
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          const: 2
        error:
          type: string
          description: Human-readable reason payment is required.
        resource:
          type: string
          description: The resource URL being purchased.
        accepts:
          type: array
          description: Payment requirement options, one per supported network (Base USDC, Solana USDC).
          items:
            type: object
            required:
            - scheme
            - network
            - amount
            - asset
            - payTo
            - maxTimeoutSeconds
            properties:
              scheme:
                type: string
                enum:
                - exact
              network:
                type: string
                description: CAIP-2 network id, e.g. "eip155:8453" (Base) or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp".
              amount:
                type: string
                description: Price in atomic asset units (USDC has 6 decimals).
              asset:
                type: string
                description: Asset contract address / mint.
              payTo:
                type: string
                description: Treasury address to pay.
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                description: 'Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).'
                additionalProperties: true
        extensions:
          type: object
          description: Optional discovery metadata (e.g. bazaar input/output schemas).
          additionalProperties: true
  responses:
    PaymentRequired:
      description: Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/X402PaymentRequiredV2'
    UpstreamError:
      description: Upstream provider error.
    MethodNotAllowed:
      description: Method not allowed — see `Allow` header for the supported method.
    ServerError:
      description: Internal server error.
    BadRequest:
      description: Bad request — invalid parameters.
  parameters:
    TrialMode:
      name: trial
      in: query
      required: false
      description: 'Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Works on every endpoint.'
      schema:
        type: integer
        enum:
        - 1
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'