openapi: 3.1.0
info:
  title: Sequence API — Headless AI SDR (Reply.io)
  version: "3.0"
  description: >
    Create, populate, and control multichannel outreach sequences.
    Summary specification for AI agents; the authoritative, complete reference is
    https://docs.reply.io/api-reference/sequences/list-all-sequences 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: Sequences
paths:
  /sequences:
    get:
      tags: [Sequences]
      operationId: listSequences
      summary: List all sequences
      description: Requires the `sequences:read` scope.
      responses:
        "200":
          description: Paginated list of sequences.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Sequence"
        "429":
          $ref: "#/components/responses/RateLimited"
    post:
      tags: [Sequences]
      operationId: createSequence
      summary: Create a sequence
      description: Requires the `sequences:write` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Sequence created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sequence"
        "403":
          $ref: "#/components/responses/Forbidden"
  /sequences/{sequenceId}:
    get:
      tags: [Sequences]
      operationId: getSequence
      summary: Get a sequence
      description: Requires the `sequences:read` scope.
      parameters:
        - $ref: "#/components/parameters/sequenceId"
      responses:
        "200":
          description: The sequence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sequence"
    patch:
      tags: [Sequences]
      operationId: updateSequence
      summary: Update a sequence
      description: Requires the `sequences:write` scope.
      parameters:
        - $ref: "#/components/parameters/sequenceId"
      responses:
        "200":
          description: Updated sequence.
    delete:
      tags: [Sequences]
      operationId: deleteSequence
      summary: Delete a sequence
      description: Requires the `sequences:write` scope.
      parameters:
        - $ref: "#/components/parameters/sequenceId"
      responses:
        "204":
          description: Deleted.
  /sequences/{sequenceId}/start:
    post:
      tags: [Sequences]
      operationId: startSequence
      summary: Start a sequence
      description: Requires the `sequences:operate` scope.
      parameters:
        - $ref: "#/components/parameters/sequenceId"
      responses:
        "200":
          description: Sequence started.
  /sequences/{sequenceId}/pause:
    post:
      tags: [Sequences]
      operationId: pauseSequence
      summary: Pause a sequence
      description: Requires the `sequences:operate` scope.
      parameters:
        - $ref: "#/components/parameters/sequenceId"
      responses:
        "200":
          description: Sequence paused.
  /sequences/{sequenceId}/stats:
    get:
      tags: [Sequences]
      operationId: getSequenceStats
      summary: Get sequence stats
      description: >
        Requires the `sequences:read` scope. May be throttled more strictly than the
        general rate limit.
      parameters:
        - $ref: "#/components/parameters/sequenceId"
      responses:
        "200":
          description: Delivery/open/click/reply/bounce statistics.
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:
    sequenceId:
      name: sequenceId
      in: path
      required: true
      schema:
        type: string
  schemas:
    Sequence:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          description: Lifecycle state (e.g. draft, active, paused, archived).
        createdAt:
          type: string
          format: date-time
    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"
