replynodes-com Discovery API

openapi: 3.2.0
info:
  title: ReplyNodes Fetcher Discovery API
  version: v1
  description: 'Read-only data APIs for AI agents. Bearer auth. Prepaid credits / free tier.


    Click **Authorize** and paste ONLY the API key (no "Bearer" prefix) — Swagger adds it automatically.'
servers:
- url: https://api.replynodes.com
security:
- bearerAuth: []
tags:
- name: Discovery
paths:
  /v1/agent/status:
    get:
      operationId: get_agent_status
      tags:
      - Discovery
      summary: Get this API key's status
      description: 'Returns the presented key''s own standing: prefix, class, status (restricted, verified, or active), expiry, per-key keyless quota for a restricted key or credit balance otherwise, and next_actions with a human_message. Reading status never consumes quota. Restricted keys can call only the keyless capability set (403 verification_required otherwise) on their own per-key daily buckets (429 restricted_limit_reached when used up).'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Key standing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentStatus'
        '401':
          description: Missing, unknown, expired, or revoked key; error.next_action is get_api_key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /v1/capabilities:
    get:
      operationId: get_gateway_capabilities
      tags:
      - Discovery
      summary: Get gateway capabilities
      description: Unauthenticated, read-only discovery of the gateway-wide provider inventory, routes currently callable under their provider manifests, and the embedded OpenAPI document. Callable discovery is a runtime snapshot, not authorization or billing state.
      security: []
      responses:
        '200':
          description: Current gateway capability registry.
          headers:
            X-Request-Id:
              description: Correlation identifier echoed as meta.request_id.
              schema:
                type: string
            X-Registry-Schema-Version:
              description: Version of the registry response envelope.
              schema:
                type: string
            X-OpenAPI-Document-Version:
              description: Version of the embedded OpenAPI document.
              schema:
                type: string
            X-OpenAPI-Document-Hash:
              description: SHA-256 identity of the embedded OpenAPI document.
              schema:
                type: string
            ETag:
              description: Quoted SHA-256 identity of the embedded OpenAPI document.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryResponse'
        '503':
          description: Normalized error with code degraded when the embedded document or callable route registry is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    AnonymousContinuation:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          const: https://replynodes.com/auth.md
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
            retryable:
              type: boolean
            reason:
              type: string
            continuation:
              $ref: '#/components/schemas/AnonymousContinuation'
            status:
              type: integer
            detail:
              type: string
            readme:
              type: string
            next_action:
              $ref: '#/components/schemas/NextAction'
          additionalProperties: false
          required:
          - code
          - message
          - request_id
      additionalProperties: false
      required:
      - error
    NextAction:
      type: object
      description: Typed next step for an agent (ADR 0024). Present only where a next step exists; branch on action, never on message text.
      required:
      - action
      - method
      - url
      - required_fields
      - docs
      properties:
        action:
          type: string
          enum:
          - get_api_key
          - verify_email
          - resend_code
          - renew_key
          - top_up
          - retry_later
          description: Closed set; values may be added, never renamed or removed.
        method:
          type: string
          enum:
          - GET
          - POST
        url:
          type: string
          format: uri
        required_fields:
          type: array
          items:
            type: string
        optional_fields:
          type: array
          items:
            type: string
        human_message:
          type: string
          description: Short sentence the agent can show its human.
        docs:
          type: string
          format: uri
        retry_after_seconds:
          type: integer
          minimum: 1
          description: When the same request may be retried without completing the action.
        auth:
          type: string
          enum:
          - bearer_api_key
          description: Credential the call needs; bearer_api_key means send the same API key as a Bearer token.
      additionalProperties: false
    RegistryBilling:
      type: object
      required:
      - metered
      properties:
        metered:
          type: boolean
        credit_cost:
          type: integer
          format: int64
          minimum: 0
      additionalProperties: false
    RegistryData:
      type: object
      required:
      - schema_version
      - service
      - version
      - documentVersion
      - documentHash
      - document
      - providers
      - callable_routes
      - openapi
      properties:
        schema_version:
          type: string
          enum:
          - v1
        service:
          type: string
        version:
          type: string
        documentVersion:
          type: string
        documentHash:
          type: string
        document:
          type: object
          description: The embedded OpenAPI document served unchanged.
        providers:
          type: array
          items:
            $ref: '#/components/schemas/RegistryProvider'
        callable_routes:
          type: array
          items:
            $ref: '#/components/schemas/RegistryRoute'
        openapi:
          $ref: '#/components/schemas/RegistryOpenAPI'
      additionalProperties: false
    AgentStatus:
      type: object
      description: A key's own standing (ADR 0024). Restricted keys report a per-key keyless quota; verified and workspace keys report their credit balance.
      required:
      - data
      - meta
      properties:
        data:
          type: object
          required:
          - key
          - quota
          - credits
          - next_actions
          properties:
            key:
              type: object
              required:
              - prefix
              - class
              - status
              - expires_at
              properties:
                prefix:
                  type: string
                class:
                  type: string
                  enum:
                  - workspace
                  - agent_read
                status:
                  type: string
                  enum:
                  - restricted
                  - verified
                  - active
                expires_at:
                  type:
                  - string
                  - 'null'
                  format: date-time
            quota:
              type:
              - object
              - 'null'
              properties:
                basis:
                  type: string
                  const: per_key_per_utc_day
                reset_at:
                  type: string
                  format: date-time
                capabilities:
                  type: object
                  additionalProperties:
                    type: object
                    required:
                    - limit
                    - remaining
                    properties:
                      limit:
                        type: integer
                      remaining:
                        type: integer
            credits:
              type:
              - object
              - 'null'
              properties:
                balance:
                  type: number
                unit:
                  type: string
                  const: credit
            next_actions:
              type: array
              items:
                $ref: '#/components/schemas/NextAction'
        meta:
          $ref: '#/components/schemas/GatewayResponseMeta'
    GatewayResponseMeta:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        contract_version:
          type: string
        generated_at:
          type: string
          format: date-time
        availability:
          type: string
        detail:
          type: string
        missing_fields:
          type: array
          items:
            type: string
        next_cursor:
          type: string
        stale:
          type: boolean
      additionalProperties: false
    RegistryProvider:
      type: object
      required:
      - slug
      - name
      - description
      - status
      - routes
      properties:
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        routes:
          type: array
          items:
            $ref: '#/components/schemas/RegistryRoute'
      additionalProperties: false
    RegistryRoute:
      type: object
      required:
      - provider
      - route
      - method
      - status
      - callable
      - auth_required
      - read_only
      - billing
      properties:
        provider:
          type: string
        operation_id:
          type: string
        tag:
          type: string
        schema_ref:
          type: string
        route:
          type: string
        method:
          type: string
          enum:
          - GET
        status:
          type: string
        callable:
          type: boolean
        auth_required:
          type: boolean
        read_only:
          type: boolean
        billing:
          $ref: '#/components/schemas/RegistryBilling'
      additionalProperties: false
    RegistryResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/RegistryData'
        meta:
          type: object
          required:
          - request_id
          properties:
            request_id:
              type: string
          additionalProperties: true
      additionalProperties: false
    RegistryOpenAPI:
      type: object
      required:
      - version
      - document_hash
      - document
      properties:
        version:
          type: string
        document_hash:
          type: string
        document:
          type: object
          description: The embedded OpenAPI document served unchanged.
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rn_test_<64hex> or rn_live_<64hex>
      description: API key. Paste the raw key only (e.g. rn_test_...) — the "Bearer " prefix is added automatically.