replynodes-com Markdown API

openapi: 3.2.0
info:
  title: ReplyNodes Fetcher Markdown 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: Markdown
paths:
  /md/{target}:
    servers:
    - url: https://md.replynodes.com
    get:
      operationId: anonymous_markdown
      tags:
      - Markdown
      summary: Read a public URL as Markdown
      description: 'Already-anonymous Markdown gateway route for canonical capability url-to-markdown (dedicated Markdown tier: 100 valid requests per trusted client-IP bucket per UTC calendar day). Admission occurs after method and target/SSRF validation and before cache/upstream work; cache hits and upstream failures consume one unit. X-RateLimit-Limit is the effective fixed tier limit, X-RateLimit-Remaining is the capability bucket balance, and X-RateLimit-Reset is the next UTC midnight Unix timestamp. Redis failure returns 503 degraded. Output format is chosen with request headers because the whole path and query string belong to the target URL: no Accept header, Accept: */*, text/markdown or text/plain returns Markdown (default); Accept: application/json (JSON preferred with q>0) returns the {data, meta} envelope with the same data shape as GET /v1/webcontext/scrape; X-Format: frontmatter returns Markdown preceded by a fixed seven-key YAML front-matter block; an unknown X-Format value, or application/json together with X-Format: frontmatter, returns 400 invalid_request with reason bad_option before any quota is spent. X-Include-Selectors and X-Exclude-Selectors (comma-separated CSS selectors, at most 10 entries and 512 bytes per header, duplicates removed, no control characters or { } ; ) filter the page; they are part of the cache key; with selectors set, a page that returns an access-check page returns 502 upstream_blocked (no crawl fallback). A page main heading may remain even when it matches an exclude selector. Every error response of this host carries error.reason (a stable value from the closed set in the MarkdownHostError schema) and error.retryable in addition to error.code, error.message and error.request_id. Successful responses set Vary: Accept, X-Format.'
      security: []
      parameters:
      - name: target
        in: path
        required: true
        schema:
          type: string
          description: Complete URL or bare public hostname, URL-encoded as needed.
      - name: X-Format
        in: header
        required: false
        description: 'Output format: markdown (default) or frontmatter. Any other value returns 400 invalid_request with reason bad_option. Cannot be combined with Accept: application/json.'
        schema:
          type: string
          enum:
          - markdown
          - frontmatter
      - name: X-Include-Selectors
        in: header
        required: false
        description: Comma-separated CSS selectors to keep (at most 10 entries, 512 bytes).
        schema:
          type: string
          example: article,.post-body
      - name: X-Exclude-Selectors
        in: header
        required: false
        description: Comma-separated CSS selectors to remove (at most 10 entries, 512 bytes).
        schema:
          type: string
          example: nav,footer,.sidebar
      responses:
        '200':
          description: Markdown by default; JSON envelope when Accept prefers application/json; Markdown with YAML front matter when X-Format is frontmatter. Quota headers are included.
          headers:
            Vary:
              schema:
                type: string
                example: Accept, X-Format
            X-Cache:
              schema:
                type: string
                enum:
                - hit
                - miss
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            text/markdown:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownJsonResponse'
        '400':
          description: Invalid target, unsafe public URL, unknown or conflicting X-Format, or invalid selector headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '404':
          description: 'Not found: the provider reports the page does not exist (reason target_not_found) or the Markdown route is not enabled on this host (reason route_disabled). Not retryable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '405':
          description: 'Method not allowed (reason method_not_allowed); Allow: GET, HEAD. Not retryable.'
          headers:
            Allow:
              schema:
                type: string
                example: GET, HEAD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '429':
          description: Anonymous daily quota exhausted. Includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, and the typed continuation. On this host the error also carries reason daily_limit and retryable false.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnonymousQuotaError'
        '451':
          description: Publisher excluded automated access (source_excluded, error.status 45101, reason publisher_excluded, not retryable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '499':
          description: The client closed the connection before the response was ready (error.code gateway_timeout, reason client_closed, retryable). Logged as 499; nothing is waiting on this response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '500':
          description: Unclassified internal error (reason internal_error, retryable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '502':
          description: Upstream_blocked (reason access_check) or upstream_unavailable (reasons target_unreachable, empty_content, content_too_large, provider_unavailable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '503':
          description: Shared Redis, the source-policy registry or quota admission unavailable; request rejected closed (reason service_degraded, retryable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
        '504':
          description: The target did not respond within 30 seconds (reason target_timeout, retryable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownHostError'
components:
  schemas:
    AnonymousContinuation:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          const: https://replynodes.com/auth.md
    AnonymousQuotaError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          - continuation
          properties:
            code:
              const: anonymous_limit_reached
            message:
              type: string
              example: 'The anonymous daily limit has been reached. Get a free API key through the browser-approved claim flow described at https://replynodes.com/auth.md: 500 free credits are granted when the first long-lived API key is created and delivered.'
            request_id:
              type: string
            continuation:
              $ref: '#/components/schemas/AnonymousContinuation'
            next_action:
              $ref: '#/components/schemas/NextAction'
    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
    MarkdownJsonResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: object
          required:
          - url
          - title
          - markdown
          - metadata
          - links
          - images
          properties:
            url:
              type: string
            title:
              type:
              - string
              - 'null'
            markdown:
              type: string
            metadata:
              type: object
              properties:
                title:
                  type:
                  - string
                  - 'null'
                description:
                  type:
                  - string
                  - 'null'
                author:
                  type:
                  - string
                  - 'null'
                image:
                  type:
                  - string
                  - 'null'
                favicon:
                  type:
                  - string
                  - 'null'
                language:
                  type:
                  - string
                  - 'null'
                published_date:
                  type:
                  - string
                  - 'null'
                site_name:
                  type:
                  - string
                  - 'null'
                word_count:
                  type:
                  - integer
                  - 'null'
                url:
                  type:
                  - string
                  - 'null'
            links:
              type: array
              items:
                type: string
            images:
              type: array
              items:
                type: string
        meta:
          type: object
          required:
          - request_id
          - generated_at
          properties:
            request_id:
              type: string
            generated_at:
              type: string
              format: date-time
              description: Time the page was fetched (the cached time on a cache hit).
    MarkdownHostError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          - reason
          - retryable
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - not_found
              - method_not_allowed
              - anonymous_limit_reached
              - source_excluded
              - upstream_blocked
              - upstream_unavailable
              - degraded
              - gateway_timeout
              - internal_error
            message:
              type: string
            request_id:
              type: string
            reason:
              type: string
              description: Stable machine-readable failure reason; a closed set (values may be added, never renamed or removed).
              enum:
              - empty_target
              - bad_scheme
              - malformed_url
              - target_too_long
              - target_not_allowed
              - target_rejected
              - bad_option
              - route_disabled
              - target_not_found
              - method_not_allowed
              - daily_limit
              - publisher_excluded
              - access_check
              - target_unreachable
              - empty_content
              - content_too_large
              - provider_unavailable
              - service_degraded
              - target_timeout
              - client_closed
              - internal_error
            retryable:
              type: boolean
              description: True when sending the identical request again later can succeed without changing anything; it says nothing about how soon.
            status:
              type: integer
              description: Stable numeric detail code; present only for source_excluded (45101).
            detail:
              type: string
              description: Safe caller guidance; present only for source_excluded.
            continuation:
              $ref: '#/components/schemas/AnonymousContinuation'
            next_action:
              $ref: '#/components/schemas/NextAction'
  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.