Flowra Chat API

openapi: 3.2.0
info:
  title: Flowra API (API Key Endpoints) Chat API
  description: '**Flowra** is an AI-powered platform for building agents, workflows, and integrations.


    ### Capabilities

    - **Tools & Toolkits** – Define and group tools for agents and workflows.

    - **Workflows** – Orchestrate steps and automate processes.

    - **Triggers** – Schedule or event-based execution.

    - **Auth & Connections** – OAuth, API keys, and connected accounts.

    - **MCP** – Model Context Protocol server integration.

    - **Knowledge / RAG** – Add files and URLs for retrieval-augmented generation.


    ### Authentication

    Use the **x-api-key** header with a project API key to access endpoints that support API Key auth. Create and manage API keys in the dashboard under your project settings.


    Only endpoints that support API Key authentication via the @ApiKeyEnabled() decorator.


    Send x-api-key (required). On multi-tenant endpoints, optionally send x-username to act as an external user.'
  version: '1.0'
  contact:
    name: Flowra
    url: https://flowra.dev
servers:
- url: https://flowra.dev
  description: Flowra API
tags:
- name: Chat
  description: Threads and streaming agent runs
paths:
  /api/v1/graphify/threads:
    post:
      operationId: GraphifyController_createThread
      x-apiKeyEnabled: true
      summary: Create thread
      description: Create a new conversation thread. Use for chat or agent sessions; each thread has its own history and state.
      parameters:
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateThreadDto'
      responses:
        '200':
          description: Thread created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadDto'
        '201':
          description: Thread created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadDto'
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}:
    get:
      operationId: GraphifyController_getThread
      x-apiKeyEnabled: true
      summary: Get thread
      description: Get a thread’s metadata and info. Use to load a conversation before continuing or to show thread details.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Thread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadDto'
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
    delete:
      operationId: GraphifyController_deleteThread
      x-apiKeyEnabled: true
      summary: Delete thread
      description: Permanently delete a thread and its conversation history. It cannot be recovered.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
    patch:
      operationId: GraphifyController_updateThread
      x-apiKeyEnabled: true
      summary: Update thread
      description: Update thread metadata such as title or custom fields. Use to rename a conversation or store tags.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateThreadDto'
      responses:
        '200':
          description: Updated thread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadDto'
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/generate-title:
    post:
      operationId: GraphifyController_generateThreadTitle
      x-apiKeyEnabled: true
      summary: Generate thread title
      description: Generate a short title for the thread from its conversation content using AI. Use to display a meaningful title in the thread list.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
        '201':
          description: ''
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/history:
    post:
      operationId: GraphifyController_getThreadHistory
      x-apiKeyEnabled: true
      summary: Get thread history
      description: 'Get the execution history for a thread: past runs, steps, and state snapshots. Use to show a timeline or debug a conversation.'
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadHistoryDto'
      responses:
        '200':
          description: Operation completed successfully
        '201':
          description: ''
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/operator-reply:
    post:
      operationId: GraphifyController_sendOperatorReply
      x-apiKeyEnabled: true
      summary: Send operator channel reply
      description: Send a message to the end user on the originating messaging channel. Requires reply mode human.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadOperatorReplyDto'
      responses:
        '200':
          description: Operation completed successfully
        '201':
          description: ''
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/reply-mode:
    patch:
      operationId: GraphifyController_setThreadReplyMode
      x-apiKeyEnabled: true
      summary: Set channel reply mode
      description: Take over a messaging-channel thread from the agent (`human`) or hand it back (`agent`). Only applies to trigger/channel conversations.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadReplyModeDto'
      responses:
        '200':
          description: Operation completed successfully
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/runs:
    get:
      operationId: GraphifyController_listRuns
      x-apiKeyEnabled: true
      summary: List thread runs
      description: List runs for a thread. Use to find an in-flight run (pending/running) so the client can rejoin its stream after leaving the chat.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: limit
        required: false
        in: query
        description: Max runs to return
        schema:
          example: 20
          type: number
      - name: offset
        required: false
        in: query
        description: Number of runs to skip
        schema:
          example: 0
          type: number
      - name: status
        required: false
        in: query
        description: Filter by LangGraph run status (e.g. pending, running, success, error)
        schema:
          example: running
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/runs/{run_id}/cancel:
    post:
      operationId: GraphifyController_cancelRun
      x-apiKeyEnabled: true
      summary: Cancel run
      description: Stop a running thread execution (e.g. when the user clicks stop in the chat). Optionally wait for the run to fully stop or rollback.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: run_id
        required: true
        in: path
        description: Run ID to cancel
        schema:
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
      - name: wait
        required: false
        in: query
        description: If true, wait until the run has fully stopped before returning
        schema:
          example: false
          type: string
      - name: action
        required: false
        in: query
        description: '`interrupt` stops the run; `rollback` reverts to the previous checkpoint'
        schema:
          enum:
          - interrupt
          - rollback
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
        '201':
          description: ''
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/runs/{run_id}/stream:
    get:
      operationId: GraphifyController_joinThreadRunStream
      x-apiKeyEnabled: true
      summary: Join run stream
      description: Join an existing run’s SSE stream. Use after navigating away so the client can resume live updates without cancelling the run.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: run_id
        required: true
        in: path
        description: Run ID to cancel
        schema:
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
      - name: cancel_on_disconnect
        required: false
        in: query
        description: If true, cancel the run when the SSE client disconnects
        schema:
          example: false
          type: string
      - name: last-event-id
        required: false
        in: header
        description: SSE Last-Event-ID to resume from after a disconnect
        schema:
          type: string
      - name: stream_mode
        required: false
        in: query
        description: LangGraph stream mode(s), e.g. values or messages-tuple
        schema:
          example: values
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/runs/stream:
    post:
      operationId: GraphifyController_streamThreadRun
      x-apiKeyEnabled: true
      summary: Stream thread run
      description: 'Run the agent/chat for this thread and stream the response via Server-Sent Events (SSE). Use for real-time chat UIs; events include message deltas and run status. A final `event: usage` reports credits for this turn and the thread total.'
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-end-user-token
        required: false
        in: header
        description: Optional host-issued identity token for the end user (HMAC/JWT). Used when the agent identity policy requires proof.
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamThreadRunDto'
      responses:
        '200':
          description: Server-sent events
          content:
            application/json:
              schema:
                type: string
                description: SSE body
        '201':
          description: Server-sent events
          content:
            application/json:
              schema:
                type: string
                description: SSE body
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/{thread_id}/state:
    get:
      operationId: GraphifyController_getThreadState
      x-apiKeyEnabled: true
      summary: Get thread state
      description: Get the current state of a thread (e.g. latest messages, checkpoint). Use to resume a conversation or inspect state for debugging.
      parameters:
      - name: thread_id
        required: true
        in: path
        description: Thread ID
        schema:
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/graphify/threads/search:
    post:
      operationId: GraphifyController_searchThreads
      x-apiKeyEnabled: true
      summary: Search threads
      description: Search conversation threads by metadata (e.g. user id, tags). Use to list or filter threads in a chat UI or dashboard.
      parameters:
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchThreadsDto'
      responses:
        '200':
          description: Operation completed successfully
        '201':
          description: ''
      tags:
      - Chat
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
components:
  schemas:
    MessageContentDto:
      type: object
      properties:
        type:
          type: string
          description: Content type
          example: text
          enum:
          - text
          - image_url
        text:
          type: string
          description: Text content
          example: Hello
        image_url:
          $ref: '#/components/schemas/ImageUrlDto'
      required:
      - type
    ThreadOperatorReplyDto:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 8000
          description: Message text sent to the end user on the originating channel
          example: Thanks — a human will take it from here.
      required:
      - text
    MessageDto:
      type: object
      properties:
        id:
          type: string
          description: Message ID
        type:
          type: string
          description: Message type
          example: human
        content:
          description: Message content
          example:
          - type: text
            text: Hello
          type: array
          items:
            $ref: '#/components/schemas/MessageContentDto'
      required:
      - type
      - content
    SearchThreadsDto:
      type: object
      properties:
        limit:
          type: number
          description: Maximum number of results to return
          example: 10
        offset:
          type: number
          description: Number of results to skip
          example: 0
        sortBy:
          type: string
          enum:
          - threadId
          - status
          - createdAt
          - updatedAt
          description: 'Sort by field (default: updatedAt for last activity first)'
        sortOrder:
          type: string
          enum:
          - asc
          - desc
          description: Sort order
    ThreadHistoryDto:
      type: object
      properties:
        limit:
          type: number
          minimum: 1
          description: Maximum number of history items to return
          example: 10
          default: 10
        checkpoint:
          type: object
          description: 'Partial checkpoint selector (e.g. `{ checkpoint_ns: "tools:<id>" }` for subgraph history)'
          example:
            checkpoint_ns: tools:abc123
        before:
          type: object
          description: Return history before this config/checkpoint
          example:
            checkpoint_id: 1ef0c2a0-...
        metadata:
          type: object
          description: Filter history by metadata
          example:
            source: chat
    ChatThreadDto:
      type: object
      properties:
        thread_id:
          type: string
          description: Thread ID
          example: b737d8af-a9e0-4251-9714-3fdc1126e5fb
        created_at:
          type: string
          description: Created at (ISO 8601)
        updated_at:
          type: string
          description: Updated at (ISO 8601)
        metadata:
          type: object
          description: Thread metadata
          additionalProperties: true
        status:
          type: string
          description: Thread status
          example: idle
        values:
          type: object
          description: Current graph values
          additionalProperties: true
      required:
      - thread_id
    ImageUrlDto:
      type: object
      properties:
        url:
          type: string
          description: Image URL (e.g. file download URL or data URL)
          example: http://localhost:10000/api/v1/file/download/xxx
      required:
      - url
    StreamThreadRunDto:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/ThreadInputDto'
        command:
          type: object
          description: 'Run command forwarded as-is (e.g. `{ "resume": { "decisions": [...] } }` for human-in-the-loop). Required when resuming without new messages.'
          example:
            resume:
              decision: approve
        stream_mode:
          description: Stream modes
          example:
          - values
          - messages-tuple
          - custom
          type: array
          items:
            type: string
        stream_subgraphs:
          type: boolean
          description: Stream subgraphs
          example: true
          default: true
        stream_resumable:
          type: boolean
          description: Stream resumable
          example: true
          default: true
        assistant_id:
          type: string
          description: Assistant ID
          example: flowra-assistant
        on_disconnect:
          type: string
          description: Action on disconnect
          example: continue
          default: continue
        workflowId:
          type: string
          description: Workflow ID (agent workflow) to use for this conversation
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          format: uuid
        model:
          type: string
          description: Optional model id override for this run (session-scoped). When set, wins over the agent workflow default model.
          example: openai/gpt-4o-mini
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          description: Optional reasoning effort override for this run (session-scoped). `none` disables workflow default reasoning. low|medium|high when the model supports reasoning_effort.
          example: none
    ThreadReplyModeDto:
      type: object
      properties:
        mode:
          type: string
          enum:
          - agent
          - human
          description: '`human` takes the thread over from the agent; `agent` hands it back. Only for trigger/channel conversations.'
          example: human
      required:
      - mode
    ThreadInputDto:
      type: object
      properties:
        messages:
          description: Messages array
          type: array
          items:
            $ref: '#/components/schemas/MessageDto'
      required:
      - messages
    CreateThreadDto:
      type: object
      properties:
        metadata:
          type: object
          description: Arbitrary thread metadata stored with the conversation (title, tags, workflowId, …).
          example:
            title: Support chat
            workflowId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          additionalProperties: true
    UpdateThreadDto:
      type: object
      properties:
        metadata:
          type: object
          description: Thread metadata to merge or replace (e.g. title, tags).
          example:
            title: Invoice follow-up
          additionalProperties: true
      required:
      - metadata
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Project API key. Create and manage keys in the dashboard under Project → API Keys. Send as header: x-api-key: <your-key>'
    x-username:
      type: apiKey
      in: header
      name: x-username
      description: 'Optional. External user username. If omitted, Flowra uses the project’s default external user. Send as header: x-username: <username>'