openapi: 3.1.0
info:
  title: AI SDR API (Jason) — Headless AI SDR (Reply.io)
  version: "3.0"
  description: >
    Program Jason, Reply's autonomous AI SDR, by managing its knowledge bases,
    offers, and playbooks. Summary specification for AI agents covering the
    operations callable today; autopilot sequences, pending approvals, insights,
    strategist, and web search are marked coming soon (targeted July 2026;
    re-verified 2026-07-05) in Reply's
    reference. The authoritative, complete reference is
    https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/create-a-knowledge-base
    and the full platform OpenAPI at https://docs.reply.io/api-reference/bundled.yaml.
  contact:
    name: Reply.io
    url: https://reply.io
servers:
  - url: https://api.reply.io/v3
security:
  - bearerAuth: []
tags:
  - name: Knowledge Bases
  - name: Offers
  - name: Playbooks
  - name: Pending Approvals
paths:
  /ai-sdr/knowledge-bases:
    get:
      tags: [Knowledge Bases]
      operationId: listKnowledgeBases
      summary: List knowledge bases
      description: Requires the `ai-sdr:read` scope.
      responses:
        "200":
          description: Paginated list of knowledge bases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/KnowledgeBase"
        "429":
          $ref: "#/components/responses/RateLimited"
    post:
      tags: [Knowledge Bases]
      operationId: createKnowledgeBase
      summary: Create a knowledge base
      description: Requires the `ai-sdr:write` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Knowledge base created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBase"
        "403":
          $ref: "#/components/responses/Forbidden"
  /ai-sdr/knowledge-bases/{knowledgeBaseId}:
    get:
      tags: [Knowledge Bases]
      operationId: getKnowledgeBase
      summary: Get a knowledge base
      description: Requires the `ai-sdr:read` scope.
      parameters:
        - $ref: "#/components/parameters/knowledgeBaseId"
      responses:
        "200":
          description: The knowledge base.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBase"
    patch:
      tags: [Knowledge Bases]
      operationId: updateKnowledgeBase
      summary: Update a knowledge base
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/knowledgeBaseId"
      responses:
        "200":
          description: Updated knowledge base.
    delete:
      tags: [Knowledge Bases]
      operationId: deleteKnowledgeBase
      summary: Delete a knowledge base
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/knowledgeBaseId"
      responses:
        "204":
          description: Deleted.
  /ai-sdr/knowledge-bases/{knowledgeBaseId}/documents:
    get:
      tags: [Knowledge Bases]
      operationId: listDocuments
      summary: List documents
      description: Requires the `ai-sdr:read` scope.
      parameters:
        - $ref: "#/components/parameters/knowledgeBaseId"
      responses:
        "200":
          description: Documents indexed into the knowledge base.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Document"
    post:
      tags: [Knowledge Bases]
      operationId: uploadDocument
      summary: Upload a document
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/knowledgeBaseId"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "201":
          description: Document uploaded and queued for indexing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
  /ai-sdr/offers:
    get:
      tags: [Offers]
      operationId: listOffers
      summary: List offers
      description: Requires the `ai-sdr:read` scope.
      responses:
        "200":
          description: Paginated list of offers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Offer"
    post:
      tags: [Offers]
      operationId: createOffer
      summary: Create an offer
      description: >
        Requires the `ai-sdr:write` scope. Generate an offer, duplicate an offer,
        and attachment upload for offer generation are marked coming soon
        (targeted July 2026) in Reply's reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Offer created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Offer"
        "403":
          $ref: "#/components/responses/Forbidden"
  /ai-sdr/offers/{offerId}:
    get:
      tags: [Offers]
      operationId: getOffer
      summary: Get an offer
      description: Requires the `ai-sdr:read` scope.
      parameters:
        - $ref: "#/components/parameters/offerId"
      responses:
        "200":
          description: The offer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Offer"
    patch:
      tags: [Offers]
      operationId: updateOffer
      summary: Update an offer
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/offerId"
      responses:
        "200":
          description: Updated offer.
    delete:
      tags: [Offers]
      operationId: deleteOffer
      summary: Delete an offer
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/offerId"
      responses:
        "204":
          description: Deleted.
  /ai-sdr/playbooks:
    get:
      tags: [Playbooks]
      operationId: listPlaybooks
      summary: List playbooks
      description: Requires the `ai-sdr:read` scope.
      responses:
        "200":
          description: Paginated list of playbooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Playbook"
    post:
      tags: [Playbooks]
      operationId: createPlaybook
      summary: Create a playbook
      description: >
        Requires the `ai-sdr:write` scope. Style files are managed with the
        Upload a style file and Delete a style file operations (same scope).
        Duplicate a playbook is marked coming soon (targeted July 2026) in Reply's reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Playbook created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Playbook"
        "403":
          $ref: "#/components/responses/Forbidden"
  /ai-sdr/playbooks/{playbookId}:
    get:
      tags: [Playbooks]
      operationId: getPlaybook
      summary: Get a playbook
      description: Requires the `ai-sdr:read` scope.
      parameters:
        - $ref: "#/components/parameters/playbookId"
      responses:
        "200":
          description: The playbook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Playbook"
    patch:
      tags: [Playbooks]
      operationId: updatePlaybook
      summary: Update a playbook
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/playbookId"
      responses:
        "200":
          description: Updated playbook.
    delete:
      tags: [Playbooks]
      operationId: deletePlaybook
      summary: Delete a playbook
      description: Requires the `ai-sdr:write` scope.
      parameters:
        - $ref: "#/components/parameters/playbookId"
      responses:
        "204":
          description: Deleted.
  /ai-sdr/pending-approvals:
    get:
      tags: [Pending Approvals]
      operationId: listPendingApprovals
      summary: List pending approvals
      description: >
        **Coming soon** — still Coming soon in Reply's reference as of 2026-07-05 (targeted early July 2026);
        no scope is published for it yet. Lists Jason's drafted messages awaiting
        a decision. Companion operations (get per contact, send, send batch,
        regenerate, reject, submit feedback) are also marked coming soon.
      responses:
        "200":
          description: Drafts awaiting a send, regenerate, or reject decision.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PendingApproval"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Reply.io API key sent as a Bearer token. Create one in the Reply.io app under
        Settings → API Key. See https://docs.reply.io/api-reference/authentication.
  parameters:
    knowledgeBaseId:
      name: knowledgeBaseId
      in: path
      required: true
      schema:
        type: string
    offerId:
      name: offerId
      in: path
      required: true
      schema:
        type: string
    playbookId:
      name: playbookId
      in: path
      required: true
      schema:
        type: string
  schemas:
    KnowledgeBase:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    Document:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    Offer:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    Playbook:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    PendingApproval:
      type: object
      description: A message Jason drafted that awaits a send, regenerate, or reject decision.
      properties:
        id:
          type: string
        contactId:
          type: string
        channel:
          type: string
        status:
          type: string
    Problem:
      type: object
      description: RFC 7807 problem document (application/problem+json).
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
  responses:
    Forbidden:
      description: The API key is missing a required scope.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    RateLimited:
      description: >
        Rate limit exceeded (100 requests/minute, 3,000/hour per user). Honor the
        Retry-After header.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
