openapi: 3.1.0
info:
  title: Conversations & Inbox API — Headless AI SDR (Reply.io)
  version: "3.0"
  description: >
    The unified Reply.io inbox as an API — read threads across email and LinkedIn,
    classify replies with categories, toggle meeting intent, and send replies.
    Summary specification for AI agents; mark read/unread, thread delete and
    bulk-delete, category get/update/delete, and bulk category assign/unassign
    operations are omitted here for brevity. The authoritative, complete reference is
    https://docs.reply.io/api-reference/inbox/list-inbox-threads 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: Inbox
paths:
  /inbox/threads:
    get:
      tags: [Inbox]
      operationId: listInboxThreads
      summary: List inbox threads
      description: Requires the `inbox:read` scope.
      responses:
        "200":
          description: Paginated list of threads across email and LinkedIn.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Thread"
        "429":
          $ref: "#/components/responses/RateLimited"
  /inbox/threads/filter:
    post:
      tags: [Inbox]
      operationId: filterInboxThreads
      summary: Filter inbox threads
      description: Requires the `inbox:read` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: Channel to match (e.g. email, linkedin).
                unread:
                  type: boolean
                categoryId:
                  type: string
      responses:
        "200":
          description: Threads matching the filter.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Thread"
        "403":
          $ref: "#/components/responses/Forbidden"
  /inbox/threads/{threadId}:
    get:
      tags: [Inbox]
      operationId: getInboxThread
      summary: Get inbox thread
      description: Requires the `inbox:read` scope.
      parameters:
        - $ref: "#/components/parameters/threadId"
      responses:
        "200":
          description: The thread.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Thread"
    delete:
      tags: [Inbox]
      operationId: deleteInboxThread
      summary: Delete inbox thread
      description: Requires the `inbox:operate` scope.
      parameters:
        - $ref: "#/components/parameters/threadId"
      responses:
        "204":
          description: Deleted.
  /inbox/threads/{threadId}/messages:
    get:
      tags: [Inbox]
      operationId: listInboxThreadMessages
      summary: List messages in an inbox thread
      description: Requires the `inbox:read` scope.
      parameters:
        - $ref: "#/components/parameters/threadId"
      responses:
        "200":
          description: Inbound and outbound messages in the thread, oldest first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Message"
  /inbox/threads/{threadId}/reply:
    post:
      tags: [Inbox]
      operationId: sendReplyWithinThread
      summary: Send a reply within a thread
      description: Requires the `inbox:operate` scope.
      parameters:
        - $ref: "#/components/parameters/threadId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
      responses:
        "200":
          description: Reply queued for sending on the thread's channel.
        "403":
          $ref: "#/components/responses/Forbidden"
  /inbox/threads/{threadId}/meeting-intent:
    post:
      tags: [Inbox]
      operationId: toggleThreadMeetingIntent
      summary: Toggle thread meeting-intent
      description: Requires the `inbox:operate` scope.
      parameters:
        - $ref: "#/components/parameters/threadId"
      responses:
        "200":
          description: Meeting-intent flag updated on the thread.
  /inbox/threads/{threadId}/ai-draft:
    post:
      tags: [Inbox]
      operationId: generateAiDraftReply
      summary: Generate an AI draft reply
      description: >
        Coming soon — still marked Coming soon in Reply's reference as of 2026-07-05
        (targeted early July 2026). A companion operation, Submit feedback on a
        generated AI draft, is targeted for late July 2026. Do not call these in
        production yet.
      parameters:
        - $ref: "#/components/parameters/threadId"
      responses:
        "200":
          description: AI-generated draft reply for the thread (not yet callable).
  /inbox/categories:
    get:
      tags: [Inbox]
      operationId: listInboxCategories
      summary: List inbox categories
      description: Requires the `inbox:read` scope.
      responses:
        "200":
          description: Reply classification categories in the workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Category"
    post:
      tags: [Inbox]
      operationId: createInboxCategory
      summary: Create inbox category
      description: Requires the `inbox:write` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Category created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Category"
        "403":
          $ref: "#/components/responses/Forbidden"
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:
    threadId:
      name: threadId
      in: path
      required: true
      schema:
        type: string
  schemas:
    Thread:
      type: object
      properties:
        id:
          type: string
        channel:
          type: string
          description: Channel the conversation lives on (e.g. email, linkedin).
        subject:
          type: string
        contactEmail:
          type: string
        unread:
          type: boolean
        categoryId:
          type: string
          description: Assigned reply classification category, if any.
        meetingIntent:
          type: boolean
        lastMessageAt:
          type: string
          format: date-time
    Message:
      type: object
      properties:
        id:
          type: string
        direction:
          type: string
          description: inbound or outbound.
        body:
          type: string
        sentAt:
          type: string
          format: date-time
    Category:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Label such as interested or not interested, or a custom value.
    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"
