replynodes-com Research API

openapi: 3.2.0
info:
  title: ReplyNodes Fetcher Research 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: Research
paths:
  /v1/company-research:
    get:
      operationId: anonymous_company_research
      tags:
      - Research
      summary: Run the anonymous company-research workflow
      description: 'Top-level anonymous company-research workflow for canonical capability company-research (fixed Tier C: 3 valid requests per trusted client-IP bucket per UTC calendar day). A valid request is admitted once, before the read-only server-side fan-out; the url-to-markdown, brand-kit, and brand-logo primitives composed inside the workflow are server-owned and never charged a second anonymous bucket. Malformed input is rejected before admission; admitted provider failures consume one unit. X-RateLimit-Limit is 3, X-RateLimit-Remaining is the Tier C bucket balance, and X-RateLimit-Reset is the next UTC midnight Unix timestamp. Redis failure returns 503 degraded.'
      security: []
      parameters:
      - name: domain
        in: query
        required: true
        schema:
          type: string
          description: 'Company domain, e.g. stripe.com. A bare public hostname only: no scheme, port, path, or credentials.'
      responses:
        '200':
          description: Composed read-only research dossier; quota headers are included.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchWorkflowResponse'
        '400':
          description: Invalid or blocked domain.
        '429':
          description: Anonymous daily quota exhausted. Includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, and the typed continuation.
          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'
        '502':
          description: Normalized error with code upstream_unavailable when every primitive read fails.
        '503':
          description: Shared Redis unavailable; request rejected closed.
  /v1/competitor-research:
    get:
      operationId: anonymous_competitor_research
      tags:
      - Research
      summary: Run the anonymous competitor-research workflow
      description: 'Top-level anonymous competitor-research workflow for canonical capability competitor-research (fixed Tier C: 3 valid requests per trusted client-IP bucket per UTC calendar day). One admitted request fans out read-only to the company domain plus up to 5 competitor domains; the whole composition is charged once and primitives are never charged a second anonymous bucket. Malformed input (missing/invalid domain, empty/invalid/oversized competitor list) is rejected before admission. See /v1/company-research for the shared quota-header contract.'
      security: []
      parameters:
      - name: domain
        in: query
        required: true
        schema:
          type: string
          description: Company domain, e.g. stripe.com.
      - name: competitors
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated competitor domains (1..5), e.g. netlify.com,cloudflare.com.
      responses:
        '200':
          description: Composed read-only research dossier with one entry per target; quota headers are included.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchWorkflowResponse'
        '400':
          description: Invalid or blocked domain, or an empty/invalid/oversized competitor list.
        '429':
          description: Anonymous daily quota exhausted. Includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, and the typed continuation.
          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'
        '502':
          description: Normalized error with code upstream_unavailable when every primitive read fails.
        '503':
          description: Shared Redis unavailable; request rejected closed.
components:
  schemas:
    ResearchWorkflowTarget:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
        brand:
          type: object
          additionalProperties: true
          description: Real brand-kit retrieve output; omitted when that primitive fails.
        styleguide:
          type: object
          additionalProperties: true
        logo:
          type: object
          additionalProperties: true
        markdown:
          type: object
          properties:
            content:
              type: string
        errors:
          type: object
          additionalProperties:
            type: string
          description: Per-primitive typed error codes; a failed primitive's output is omitted rather than fabricated.
    AnonymousContinuation:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          const: https://replynodes.com/auth.md
    ResearchWorkflowData:
      type: object
      required:
      - workflow
      - domain
      - targets
      properties:
        workflow:
          type: string
          enum:
          - company-research
          - competitor-research
        domain:
          type: string
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ResearchWorkflowTarget'
    ResearchWorkflowResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/ResearchWorkflowData'
        meta:
          type: object
          additionalProperties: true
    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
  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.