Aveco Sequences API

openapi: 3.2.0
info:
  title: Aveco Sequences API
  version: 0.1.0
tags:
- name: Sequences
paths:
  /api/sequences/{sequence_id}/readiness:
    get:
      summary: Sequence Launch Readiness
      operationId: sequence_launch_readiness_api_sequences__sequence_id__readiness_get
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/legacy/{legacy_id}:
    get:
      summary: Sequences Legacy Detail
      operationId: sequences_legacy_detail_api_sequences_legacy__legacy_id__get
      parameters:
      - name: legacy_id
        in: path
        required: true
        schema:
          type: string
          title: Legacy Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/legacy/{legacy_id}/enrollments:
    get:
      summary: Sequences Legacy Enrollments
      description: 'Read-only per-lead listing for a legacy campaign''s Audience panel —

        same row shape as the real-Sequence `/enrollments` endpoint

        (SequenceEnrollmentRow), sourced from that channel''s own lead/enrollment

        table instead of OutreachSequenceEnrollment.'
      operationId: sequences_legacy_enrollments_api_sequences_legacy__legacy_id__enrollments_get
      parameters:
      - name: legacy_id
        in: path
        required: true
        schema:
          type: string
          title: Legacy Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/meta:
    get:
      summary: Sequences Meta
      operationId: sequences_meta_api_sequences_meta_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Sequences
  /api/sequences/snippets:
    get:
      summary: Sequences Snippets List
      operationId: sequences_snippets_list_api_sequences_snippets_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Sequences
    post:
      summary: Sequences Snippets Create
      operationId: sequences_snippets_create_api_sequences_snippets_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnippetBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/snippets/{snippet_id}:
    delete:
      summary: Sequences Snippets Delete
      operationId: sequences_snippets_delete_api_sequences_snippets__snippet_id__delete
      parameters:
      - name: snippet_id
        in: path
        required: true
        schema:
          type: integer
          title: Snippet Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/comparison:
    get:
      summary: Sequences Comparison
      description: 'plan §11 — compare every sequence in the project side by side:

        enrolled / completed / reply rate / qualified share / median hours to

        first reply.'
      operationId: sequences_comparison_api_sequences_comparison_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Sequences
  /api/sequences:
    post:
      summary: Sequences Create
      operationId: sequences_create_api_sequences_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequenceCreateBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}:
    get:
      summary: Sequences Detail
      operationId: sequences_detail_api_sequences__sequence_id__get
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
    put:
      summary: Sequences Update Settings
      operationId: sequences_update_settings_api_sequences__sequence_id__put
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequenceSettingsBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
    delete:
      summary: Sequences Delete
      operationId: sequences_delete_api_sequences__sequence_id__delete
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/graph:
    post:
      summary: Sequences Save Graph
      description: 'Replaces the whole node/edge set (plan §5.5 autosave). Enrollments

        reference nodes by `node_key`, not row id, so a full delete+recreate here

        is safe as long as node_keys already in use are kept — see plan §5.7 for

        the live-edit guardrails this MVP still owes (open risk §12).'
      operationId: sequences_save_graph_api_sequences__sequence_id__graph_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/aveco__webapp__routes__sequences__GraphSaveBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/publish:
    post:
      summary: Sequences Publish
      operationId: sequences_publish_api_sequences__sequence_id__publish_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PublishBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/status:
    post:
      summary: Sequences Set Status
      operationId: sequences_set_status_api_sequences__sequence_id__status_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/aveco__webapp__routes__sequences__StatusBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/stats:
    get:
      summary: Sequences Stats
      description: 'Live per-node stats (plan §5.4) — how many enrollments are on each

        node right now, how many ever passed through, and the conversion split

        on every branching edge.'
      operationId: sequences_stats_api_sequences__sequence_id__stats_get
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/simulate:
    post:
      summary: Sequences Simulate
      description: 'Dry-run walk of the graph for one real contact (plan §5.8 "Тест" mode)

        — never writes an enrollment or touches any channel. Condition nodes

        that can''t be resolved right now (most can''t — they depend on a reply

        that hasn''t happened) take their "no"/timeout branch, clearly labeled as

        such in the response so the preview reads as "if nothing happens" rather

        than a real prediction.'
      operationId: sequences_simulate_api_sequences__sequence_id__simulate_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/test-send:
    post:
      summary: Sequences Test Send
      description: 'Send ONE real test message of an email step to the signed-in user''s own

        address (never to a contact), with merge tags filled from a sample contact.

        Uses the step''s chosen mailbox, or the project''s first active one. Other

        channels are preview-only: sending a "test" through a Telegram/LinkedIn

        account risks that account for no benefit.'
      operationId: sequences_test_send_api_sequences__sequence_id__test_send_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestSendBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/enrollments/{enrollment_id}/advance-task:
    post:
      summary: Sequences Advance Task
      description: 'Manually unblocks one enrollment stuck at a `task` node (plan §5.1 —

        task nodes wait for a human, the orchestrator never advances them on its

        own). The orchestrator''s own tick picks it up on its next pass since

        this just clears next_action_at back to "now".'
      operationId: sequences_advance_task_api_sequences__sequence_id__enrollments__enrollment_id__advance_task_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      - name: enrollment_id
        in: path
        required: true
        schema:
          type: integer
          title: Enrollment Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdvanceTaskBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/nodes/{node_key}/move-enrollments:
    post:
      summary: Sequences Move Enrollments
      description: 'plan §5.7 — relocate every active contact currently sitting on

        `node_key` onto `to_node_key` (e.g. before deleting a step). The

        orchestrator picks them up next tick as if they''d just entered the

        target node.'
      operationId: sequences_move_enrollments_api_sequences__sequence_id__nodes__node_key__move_enrollments_post
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      - name: node_key
        in: path
        required: true
        schema:
          type: string
          title: Node Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveEnrollmentsBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/enrollments:
    get:
      summary: Sequences Enrollments
      description: 'Read-only «Аудитория/Лиды» listing at the Sequence level (master plan

        §4.2/§4 stage A.5) — one row per `OutreachSequenceEnrollment`, contact

        identity resolved from `ContactPerson`/`ContactMethod`/`ContactOrganization`

        rather than a channel-specific Lead row, since a node''s audience concept

        doesn''t apply once contacts flow through enrollment.'
      operationId: sequences_enrollments_api_sequences__sequence_id__enrollments_get
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/nodes/{node_key}/email-analytics:
    get:
      summary: Sequences Node Email Analytics
      description: 'Drill-down analytics for one `send:email` node (master plan §5 /

        stage A.5) — resolves the node''s shadow `OutreachEmailCampaign`

        (`sequence_node_ref = "seq::"`) and forwards to the

        existing per-campaign meta endpoint, which already has everything

        `EmailCampaignAnalyticsTab` renders (leads_by_status/send_outcomes/

        tracking/variants). No new stats logic — same shape, node-scoped.'
      operationId: sequences_node_email_analytics_api_sequences__sequence_id__nodes__node_key__email_analytics_get
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      - name: node_key
        in: path
        required: true
        schema:
          type: string
          title: Node Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/{sequence_id}/funnel:
    get:
      summary: Sequences Funnel
      description: 'plan §11 — per-node funnel: total enrolled → how many distinct

        enrollments ever reached each node → branch split on every fork →

        exit-reason breakdown. Straight read of OutreachSequenceNodeEvent.'
      operationId: sequences_funnel_api_sequences__sequence_id__funnel_get
      parameters:
      - name: sequence_id
        in: path
        required: true
        schema:
          type: integer
          title: Sequence Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
  /api/sequences/generate-draft:
    post:
      summary: Sequences Generate Draft
      description: 'plan §4.3 — returns a TemplateSpec-shaped graph preview. Does NOT

        create an OutreachSequence; the client calls the existing

        `POST /api/sequences` + `.../graph` only after the user accepts the

        preview, so the generator can''t write to the DB on its own.'
      operationId: sequences_generate_draft_api_sequences_generate_draft_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/aveco__webapp__routes__sequences__GenerateDraftBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Sequences
components:
  schemas:
    AdvanceTaskBody:
      properties:
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      type: object
      title: AdvanceTaskBody
    TestSendBody:
      properties:
        node_key:
          type: string
          title: Node Key
      type: object
      required:
      - node_key
      title: TestSendBody
    aveco__webapp__routes__sequences__GenerateDraftBody:
      properties:
        offer_description:
          type: string
          title: Offer Description
        icp_description:
          type: string
          title: Icp Description
          default: ''
        channels:
          items:
            type: string
          type: array
          title: Channels
          default: []
        tone:
          anyOf:
          - type: string
          - type: 'null'
          title: Tone
      type: object
      required:
      - offer_description
      title: GenerateDraftBody
    aveco__webapp__routes__sequences__GraphSaveBody:
      properties:
        nodes:
          items:
            $ref: '#/components/schemas/aveco__webapp__routes__sequences__GraphNodeBody'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/GraphEdgeBody'
          type: array
          title: Edges
        force:
          type: boolean
          title: Force
          default: false
        ai_generated:
          type: boolean
          title: Ai Generated
          default: false
      type: object
      required:
      - nodes
      - edges
      title: GraphSaveBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MoveEnrollmentsBody:
      properties:
        to_node_key:
          type: string
          title: To Node Key
      type: object
      required:
      - to_node_key
      title: MoveEnrollmentsBody
    PublishBody:
      properties:
        edit_scope:
          type: string
          title: Edit Scope
          default: all
      type: object
      title: PublishBody
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    aveco__webapp__routes__sequences__GraphNodeBody:
      properties:
        node_key:
          type: string
          title: Node Key
        node_type:
          type: string
          title: Node Type
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        config:
          additionalProperties: true
          type: object
          title: Config
          default: {}
        position:
          additionalProperties: true
          type: object
          title: Position
          default:
            x: 0
            y: 0
        position_manual:
          type: boolean
          title: Position Manual
          default: false
      type: object
      required:
      - node_key
      - node_type
      title: GraphNodeBody
    SequenceSettingsBody:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        source_organization_base_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Organization Base Id
        source_contact_list_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Contact List Id
        daily_new_leads_cap:
          anyOf:
          - type: integer
          - type: 'null'
          title: Daily New Leads Cap
        quiet_hours_json:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Quiet Hours Json
        skip_recently_contacted_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Skip Recently Contacted Days
        auto_research_on_intake:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Auto Research On Intake
        stop_on_reply:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Stop On Reply
        sender_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Mode
        team_member_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Team Member Ids
      type: object
      title: SequenceSettingsBody
    SimulateBody:
      properties:
        contact_person_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Contact Person Id
      type: object
      title: SimulateBody
    SnippetBody:
      properties:
        name:
          type: string
          title: Name
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        subject:
          anyOf:
          - type: string
          - type: 'null'
          title: Subject
        body:
          type: string
          title: Body
          default: ''
      type: object
      required:
      - name
      title: SnippetBody
    SequenceCreateBody:
      properties:
        name:
          type: string
          title: Name
        source_organization_base_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Organization Base Id
        sender_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Mode
        source_contact_list_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Contact List Id
      type: object
      required:
      - name
      title: SequenceCreateBody
    GraphEdgeBody:
      properties:
        from_node_key:
          type: string
          title: From Node Key
        to_node_key:
          type: string
          title: To Node Key
        branch_key:
          type: string
          title: Branch Key
          default: default
      type: object
      required:
      - from_node_key
      - to_node_key
      title: GraphEdgeBody
    aveco__webapp__routes__sequences__StatusBody:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: StatusBody