openapi: 3.2.0
info:
  title: 2s — the (most) everything Job 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: Job
paths:
  /api/job/federal-codes:
    get:
      tags:
      - Job
      summary: Fetch a USAJobs reference codelist (lookup tables behind
      description: 'Fetch a USAJobs reference codelist (lookup tables behind every federal job posting). Pass name to pick which list: agencysubelements (every agency + sub-element), occupationalseries (2210 IT, 0301 Misc Admin, 0801 Engineer, etc.), paygrades, payplans (GS, SES, ES, WG, etc.), hiringpaths (veteran, military spouse, native American, etc.), securityclearances, locationcodes, countries, countrysubdivisions, ethnicities, racecodes, militarystatuscodes, languagecodes, positionscheduletypecodes (full-time/part-time/seasonal), travelpercentages, missioncriticalcodes, cyberworkroles, etc. (33 lists total). Use the returned codes as filter inputs to /api/job/federal-search.'
      operationId: job_federal-codes
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = the requested USAJobs reference codelist entries; total = entry count; meta.name + meta.dateGenerated identify the list.'
          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: {}
                          additionalProperties: true
                          description: Raw USAJobs codelist entry — column set varies by list (typically Code, Value, LastModified, IsDisabled; some lists add extras like JobFamily).
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          name:
                            type: string
                            enum:
                            - academichonors
                            - agencysubelements
                            - announcementclosingtypes
                            - applicantsuppliers
                            - cyberworkroles
                            - countries
                            - countrysubdivisions
                            - degreetypecodes
                            - documentations
                            - ethnicities
                            - federalemploymentstatuses
                            - geoloccodes
                            - hiringpaths
                            - languagecodes
                            - languageproficiencies
                            - locationcodes
                            - militarystatuscodes
                            - missioncriticalcodes
                            - occupationalseries
                            - paygrades
                            - payplans
                            - positionofferingtypecodes
                            - positionopeningstatuses
                            - positionscheduletypecodes
                            - racecodes
                            - refereetypecodes
                            - remunerationrateintervalcodes
                            - requiredstandarddocuments
                            - securityclearances
                            - servicetypes
                            - specialhirings
                            - travelpercentages
                            - whomayapply
                          dateGenerated:
                            type: string
                            nullable: true
                        required:
                        - name
                        - dateGenerated
                        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: job.federal-codes
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: query
        required: true
        description: Name to search for.
        schema:
          type: string
          enum:
          - academichonors
          - agencysubelements
          - announcementclosingtypes
          - applicantsuppliers
          - cyberworkroles
          - countries
          - countrysubdivisions
          - degreetypecodes
          - documentations
          - ethnicities
          - federalemploymentstatuses
          - geoloccodes
          - hiringpaths
          - languagecodes
          - languageproficiencies
          - locationcodes
          - militarystatuscodes
          - missioncriticalcodes
          - occupationalseries
          - paygrades
          - payplans
          - positionofferingtypecodes
          - positionopeningstatuses
          - positionscheduletypecodes
          - racecodes
          - refereetypecodes
          - remunerationrateintervalcodes
          - requiredstandarddocuments
          - securityclearances
          - servicetypes
          - specialhirings
          - travelpercentages
          - whomayapply
      - $ref: '#/components/parameters/TrialMode'
  /api/job/federal-search:
    get:
      tags:
      - Job
      summary: Search current US federal job postings via the USAJobs API
      description: 'Search current US federal job postings via the USAJobs API. Filter by keyword, positionTitle, locationName ("Washington, DC" or city/zip), remote (telework-eligible), pay grade range (e.g. payGradeLow=GS09 + payGradeHigh=GS13), jobCategoryCode (occupational series, e.g. 2210 for IT), organization (agency sub-element code, e.g. TR40 for IRS), whoMayApply (all/public/status). Returns per-posting: control number, position ID, title, USAJobs URL + apply URL, organization + department, locations, schedule, offering type, pay scales (min/max + interval), publication start + application close, qualification summary, job category + grade. Use sortField + sortDirection to sort. Pagination via resultsPerPage + page.'
      operationId: job_federal-search
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matched federal job postings; total = upstream total match count; meta.count = postings on this page.'
          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:
                            controlNumber:
                              type: string
                              nullable: true
                            positionId:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            uri:
                              type: string
                              nullable: true
                            applyUri:
                              type: array
                              items:
                                type: string
                            organization:
                              type: string
                              nullable: true
                            department:
                              type: string
                              nullable: true
                            locations:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                            remote:
                              type: boolean
                            schedule:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                            offeringType:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                            payScales:
                              type: array
                              items:
                                type: object
                                properties:
                                  min:
                                    type: number
                                    nullable: true
                                  max:
                                    type: number
                                    nullable: true
                                  interval:
                                    type: string
                                    nullable: true
                                required:
                                - min
                                - max
                                - interval
                                additionalProperties: false
                            publicationStart:
                              type: string
                              nullable: true
                            applicationClose:
                              type: string
                              nullable: true
                            qualificationSummary:
                              type: string
                              nullable: true
                            jobCategory:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                            jobGrade:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                          required:
                          - controlNumber
                          - positionId
                          - title
                          - uri
                          - applyUri
                          - organization
                          - department
                          - locations
                          - remote
                          - schedule
                          - offeringType
                          - payScales
                          - publicationStart
                          - applicationClose
                          - qualificationSummary
                          - jobCategory
                          - jobGrade
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: Postings returned on this page.
                        required:
                        - count
                        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: job.federal-search
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: keyword
        in: query
        required: false
        description: Keyword.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: positionTitle
        in: query
        required: false
        description: Position title.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: locationName
        in: query
        required: false
        description: Location name.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: remote
        in: query
        required: false
        description: Remote.
        schema:
          type: boolean
      - name: payGradeLow
        in: query
        required: false
        description: Pay grade low.
        schema:
          type: string
          pattern: ^[A-Z]{2}\d{2}$
      - name: payGradeHigh
        in: query
        required: false
        description: Pay grade high.
        schema:
          type: string
          pattern: ^[A-Z]{2}\d{2}$
      - name: jobCategoryCode
        in: query
        required: false
        description: Job category code.
        schema:
          type: string
          pattern: ^\d{3,4}$
      - name: organization
        in: query
        required: false
        description: Organization.
        schema:
          type: string
          pattern: ^[A-Z0-9]{2,6}$
      - name: whoMayApply
        in: query
        required: false
        description: Who may apply.
        schema:
          type: string
          enum:
          - all
          - public
          - status
      - name: resultsPerPage
        in: query
        required: false
        description: Results per page.
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: sortField
        in: query
        required: false
        description: Sort field.
        schema:
          type: string
          enum:
          - OpenDate
          - CloseDate
          - PositionTitle
          - Salary
      - name: sortDirection
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - Asc
          - Desc
      - $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.'