FlowCastle

FlowCastle API

FlowCastle API as documented publicly: 12 operations. Contract generated from the documentation by API Evangelist (2026-11-08); not the provider's own document.

GitHub OpenAPI

Operations 12

POST /api/mcp FlowCastle exposes an MCP server over Streamable HTTP #
POST /api/sdk/v1/events matched flow event uses handled: true ; update_id is stable when Telegram supplies it #
GET /api/sdk/v1/jobs When enabled (the default), the plugin also pulls outbound delivery jobs from FlowCastle — e.g. replies a human agent types in the Live Chat inbox — and executes them through your #
POST /api/sdk/v1/jobs/ack When enabled (the default), the plugin also pulls outbound delivery jobs from FlowCastle — e.g. replies a human agent types in the Live Chat inbox — and executes them through your #
GET /api/sdk/v1/manifest Retrieve the trigger manifest #
GET /claims Fetch active conversation ownership #
POST /events Send observed or handled sanitized updates #
GET /jobs Lease, execute, and report outbound work #
POST /jobs/ack Lease token is returned in ack; execute per-chat FIFO; error acks retain Telegram code/description where available #
GET /manifest Fetch versioned trigger rules #
POST /runtime-runs Explicit customer-code flow start #
POST /runtime/heartbeat Bind/report runtime identity #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/flowcastle-ai/openapi/_ae-authored/flowcastle-ai-openapi-generated.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/flowcastle-ai/json-schema/flowcastle-ai-get-api-sdk-v1-manifest-response-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/flowcastle-ai:flowcastle-ai-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

flowcastle-ai-openapi-generated.yml Raw ↑ 
openapi: 3.1.0
info:
  title: FlowCastle API
  version: '2026-11-08'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-08: 12 operation(s) read from 6 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; FlowCastle has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 12
    pages-with-code: 0
    pages-read: 6
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-08'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
  - https://github.com/FlowCastle/flowcastle-sdk/blob/main/packages/sdk-grammy/README.md
  - https://github.com/FlowCastle/telegram-bot-templates
  - https://github.com/FlowCastle/flowcastle-sdk/blob/main/packages/sdk-grammy
  - https://github.com/FlowCastle/flowcastle-sdk/tree/main/packages/sdk-grammy
  - https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/SDK_GRAMMY_PROXY_FLOW_RUNTIME_PLAN.md
servers:
- url: https://my.flowcastle.ai
paths:
  /api/mcp:
    post:
      operationId: post_api_mcp
      tags:
      - Api
      summary: FlowCastle exposes an MCP server over Streamable HTTP
      description: 'POST https://api.flowcastle.ai/api/mcp with Authorization: Bearer <your-application-api-key>.'
      x-source: https://github.com/FlowCastle/telegram-bot-templates
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/sdk/v1/events:
    post:
      operationId: post_api_sdk_v1_events
      tags:
      - Api
      summary: 'matched flow event uses handled: true ; update_id is stable when Telegram supplies it'
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/sdk/v1/jobs:
    get:
      operationId: get_api_sdk_v1_jobs
      tags:
      - Api
      summary: When enabled (the default), the plugin also pulls outbound delivery jobs from FlowCastle — e.g. replies a human agent types in
        the Live Chat inbox — and executes them through your bot's own Telegram c
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/packages/sdk-grammy/README.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/sdk/v1/jobs/ack:
    post:
      operationId: post_api_sdk_v1_jobs_ack
      tags:
      - Api
      summary: When enabled (the default), the plugin also pulls outbound delivery jobs from FlowCastle — e.g. replies a human agent types in
        the Live Chat inbox — and executes them through your bot's own Telegram c
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/packages/sdk-grammy/README.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/sdk/v1/manifest:
    get:
      operationId: get_api_sdk_v1_manifest
      tags:
      - Api
      summary: Retrieve the trigger manifest
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/SDK_GRAMMY_PROXY_FLOW_RUNTIME_PLAN.md
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiSdkV1ManifestResponse'
      x-evidence:
        kind: documentation
  /claims:
    get:
      operationId: get_claims
      tags:
      - Claims
      summary: Fetch active conversation ownership
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /events:
    post:
      operationId: post_events
      tags:
      - Events
      summary: Send observed or handled sanitized updates
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /jobs:
    get:
      operationId: get_jobs
      tags:
      - Jobs
      summary: Lease, execute, and report outbound work
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /jobs/ack:
    post:
      operationId: post_jobs_ack
      tags:
      - Jobs
      summary: Lease token is returned in ack; execute per-chat FIFO; error acks retain Telegram code/description where available
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /manifest:
    get:
      operationId: get_manifest
      tags:
      - Manifest
      summary: Fetch versioned trigger rules
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /runtime-runs:
    post:
      operationId: post_runtime_runs
      tags:
      - Runtime Runs
      summary: Explicit customer-code flow start
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /runtime/heartbeat:
    post:
      operationId: post_runtime_heartbeat
      tags:
      - Runtime
      summary: Bind/report runtime identity
      x-source: https://github.com/FlowCastle/flowcastle-sdk/blob/main/docs/CROSS_FRAMEWORK_TELEGRAM_SDK_PLAN.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiSdkV1ManifestResponse:
      type: object
      properties:
        version:
          type: string
          description: Deploy id / etag
        commands:
          type: array
          description: List of command strings
        keywords:
          type: array
          description: Array of keyword match objects
        deepLinkPrefixes:
          type: array
          description: Deep‑link prefixes
        callbackPrefixes:
          type: array
          description: Callback prefixes
        catchAll:
          type: boolean
          description: Whether a flow has an unfiltered message trigger
        chatTypes:
          type: array
          description: Allowed chat types
tags:
- name: Api
- name: Claims
- name: Events
- name: Jobs
- name: Manifest
- name: Runtime
- name: Runtime Runs