openapi: 3.2.0
info:
  title: 2s — the (most) everything Maritime 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: maritime
paths:
  /api/maritime/cases:
    get:
      tags:
      - maritime
      summary: US Coast Guard activity / port-state-control case history
      description: US Coast Guard activity / port-state-control case history for a vessel, by USCG vessel id (from maritime.vessel). Returns cases newest-first with the activity id, start date, type (Boarding, Inspection, Investigation, etc.), and process status. Keyless, public-domain. The compliance/inspection record behind a vessel — use for safety and counterparty due diligence.
      operationId: maritime_cases
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = activity/PSC cases (newest first); total = case count.'
          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:
                            activityId:
                              type: number
                              nullable: true
                            startDate:
                              type: string
                              nullable: true
                            type:
                              type: string
                              nullable: true
                            status:
                              type: string
                              nullable: true
                            statusDetail:
                              type: string
                              nullable: true
                          required:
                          - activityId
                          - startDate
                          - type
                          - status
                          - statusDetail
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    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: maritime.cases
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: vesselId
        in: query
        required: true
        description: Vessel ID.
        schema:
          type: string
          pattern: ^\d+$
      - $ref: '#/components/parameters/TrialMode'
  /api/maritime/port:
    get:
      tags:
      - maritime
      summary: Look up world ports and terminals in the NGA World Port
      description: Look up world ports and terminals in the NGA World Port Index (Pub 150, ~2,950 ports) by port name (partial match) and/or country (full country name, e.g. "Japan"). Returns matching ports with location (lat/lon, country, region), UN/LOCODE, harbor size/type and shelter, max vessel length/draft (meters), channel/anchorage/cargo-pier depths, tidal range, and chart number. Keyless, public-domain (NGA). Physical-port reference data an LLM cannot reliably recall; complements maritime.vessel (USCG vessel registry) and maritime.cases (port-state-control inspections).
      operationId: maritime_port
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching ports (sliced to limit); total = full match count.'
          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:
                            portNumber:
                              type: string
                              nullable: true
                            portName:
                              type: string
                              nullable: true
                            countryCode:
                              type: string
                              nullable: true
                            countryName:
                              type: string
                              nullable: true
                            regionName:
                              type: string
                              nullable: true
                            latitude:
                              type: number
                              nullable: true
                            longitude:
                              type: number
                              nullable: true
                            harborSize:
                              type: string
                              nullable: true
                            harborType:
                              type: string
                              nullable: true
                            shelter:
                              type: string
                              nullable: true
                            maxVesselLengthM:
                              type: number
                              nullable: true
                            maxVesselDraftM:
                              type: number
                              nullable: true
                            channelDepthM:
                              type: number
                              nullable: true
                            anchorageDepthM:
                              type: number
                              nullable: true
                            cargoPierDepthM:
                              type: number
                              nullable: true
                            tidalRangeM:
                              type: number
                              nullable: true
                            unLocode:
                              type: string
                              nullable: true
                            chartNumber:
                              type: string
                              nullable: true
                          required:
                          - portNumber
                          - portName
                          - countryCode
                          - countryName
                          - regionName
                          - latitude
                          - longitude
                          - harborSize
                          - harborType
                          - shelter
                          - maxVesselLengthM
                          - maxVesselDraftM
                          - channelDepthM
                          - anchorageDepthM
                          - cargoPierDepthM
                          - tidalRangeM
                          - unLocode
                          - chartNumber
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    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: maritime.port
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: portName
        in: query
        required: false
        description: Port name.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: country
        in: query
        required: false
        description: Country name or ISO country code.
        schema:
          type: string
          minLength: 1
          maxLength: 60
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/maritime/vessel:
    get:
      tags:
      - maritime
      summary: Look up vessels in the US Coast Guard PSIX registry by name
      description: Look up vessels in the US Coast Guard PSIX registry by name (partial match), call sign, official number, hull number (HIN), flag country, service type, or build year. Returns matching vessels with the USCG vessel id, name, call sign, service type, build year, status, official number, HIN, and flag. Keyless, public-domain. Covers US-flagged vessels (and foreign vessels with US port-state-control activity). Pair the returned vesselId with maritime.cases for the inspection record. (Cross-references trade.locode for ports.)
      operationId: maritime_vessel
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching vessels; total = match count.'
          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:
                            vesselId:
                              type: number
                              nullable: true
                            name:
                              type: string
                              nullable: true
                            callSign:
                              type: string
                              nullable: true
                            serviceType:
                              type: string
                              nullable: true
                            buildYear:
                              type: number
                              nullable: true
                            status:
                              type: string
                              nullable: true
                            officialNumber:
                              type: string
                              nullable: true
                            hullNumber:
                              type: string
                              nullable: true
                            flag:
                              type: string
                              nullable: true
                          required:
                          - vesselId
                          - name
                          - callSign
                          - serviceType
                          - buildYear
                          - status
                          - officialNumber
                          - hullNumber
                          - flag
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    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: maritime.vessel
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: query
        required: false
        description: Name to search for.
        schema:
          type: string
          maxLength: 100
      - name: callSign
        in: query
        required: false
        description: Call sign.
        schema:
          type: string
          maxLength: 40
      - name: officialNumber
        in: query
        required: false
        description: Official number.
        schema:
          type: string
          maxLength: 40
      - name: hullNumber
        in: query
        required: false
        description: Hull number.
        schema:
          type: string
          maxLength: 40
      - name: flag
        in: query
        required: false
        description: Flag.
        schema:
          type: string
          maxLength: 60
      - name: service
        in: query
        required: false
        description: Service.
        schema:
          type: string
          maxLength: 60
      - name: buildYear
        in: query
        required: false
        description: Build year.
        schema:
          type: string
          pattern: ^\d{4}$
      - name: vesselId
        in: query
        required: false
        description: Vessel ID.
        schema:
          type: string
          pattern: ^\d+$
      - $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.'