# VyomFlow API

- [VyomFlow API: Build AI Chat Experiences](https://docs.vyomflow.co.in/index.md): VyomFlow API lets you build AI-powered chat experiences with agents, tool calls, real-time streaming, and file attachments in one REST API.
- [Get Started with VyomFlow API](https://docs.vyomflow.co.in/quickstart.md): Make your first VyomFlow API request against production: create a chat, send a message, stream the response, and check your credit balance.
- [Authenticate Requests to the VyomFlow API](https://docs.vyomflow.co.in/authentication.md): The public VyomFlow API (api.vyomflow.co.in/api/public/v1 and /api/mcp) is authenticated with a scoped, Clerk-issued API key sent as a bearer token.
- [Chats: Persistent Conversation Containers](https://docs.vyomflow.co.in/concepts/chats.md): A Chat is the top-level container for a conversation in VyomFlow. Learn about the Chat object, its lifecycle, and how to manage chat lists.
- [Agent Runs: How the AI Processes Your Messages](https://docs.vyomflow.co.in/concepts/runs.md): A Run is created each time you send a message. It tracks the agent execution lifecycle, tool calls, streaming output, and completion status.
- [Waitpoints: Pause a Run for Human Input](https://docs.vyomflow.co.in/concepts/waitpoints.md): Waitpoints let a running agent pause and wait for external input before continuing. Learn how to detect and respond to waitpoints.
- [Attachments: Send Files with Your Messages](https://docs.vyomflow.co.in/concepts/attachments.md): Attachments let you upload files and include them in agent messages. Learn the three-step upload flow: request upload params, upload to storage, then mark complete.
- [Stream a Run's Output](https://docs.vyomflow.co.in/streaming.md): Server-Sent Events reference for GET /api/public/v1/runs/{runId}/stream — event types, resume semantics, reconnect protocol, and heartbeat behavior.
- [Connect an MCP Client to VyomFlow](https://docs.vyomflow.co.in/mcp.md): VyomFlow exposes an 8-tool Model Context Protocol server over streamable HTTP, authenticated with the same API keys as the REST API.
- [Webhooks](https://docs.vyomflow.co.in/webhooks.md): Register an outbound webhook endpoint to receive signed notifications when a run starts, completes, fails, or a tool finishes.
- [Error Codes and Responses](https://docs.vyomflow.co.in/errors.md): Every VyomFlow API error returns a uniform JSON envelope. This page lists all status codes, error codes, and what to do when you see them.
- [Rate Limits for the VyomFlow API](https://docs.vyomflow.co.in/rate-limits.md): The VyomFlow API enforces per-user send-rate limits on message submission to protect shared provider budgets.
- [How Credits Work in VyomFlow](https://docs.vyomflow.co.in/credits.md): Credits control access to tool calls (image generation, cropping, and video merging). Learn how admission, reservation, and settlement work during an agent turn.
- [VyomFlow API Reference Overview](https://docs.vyomflow.co.in/api-reference/introduction.md): Base URL, authentication, versioning, and common patterns for the VyomFlow public REST API.
- [List the caller's chats (cursor-paginated, newest first)](https://docs.vyomflow.co.in/api-reference/chats/list-the-callers-chats-cursor-paginated-newest-first.md)
- [Create a chat](https://docs.vyomflow.co.in/api-reference/chats/create-a-chat.md)
- [Get a chat](https://docs.vyomflow.co.in/api-reference/chats/get-a-chat.md)
- [Soft-delete a chat](https://docs.vyomflow.co.in/api-reference/chats/soft-delete-a-chat.md)
- [Rename a chat](https://docs.vyomflow.co.in/api-reference/chats/rename-a-chat.md)
- [Pin (favorite) a chat](https://docs.vyomflow.co.in/api-reference/chats/pin-favorite-a-chat.md)
- [Unpin a chat](https://docs.vyomflow.co.in/api-reference/chats/unpin-a-chat.md)
- [List a chat's messages (cursor-paginated)](https://docs.vyomflow.co.in/api-reference/messages/list-a-chats-messages-cursor-paginated.md)
- [Submit a message and start (or continue) an agent turn](https://docs.vyomflow.co.in/api-reference/messages/submit-a-message-and-start-or-continue-an-agent-turn.md): Reserves credit admission, persists the user message, and dispatches a durable Trigger.dev turn. One active run per chat is enforced — a second send while a run is active returns 409 CONFLICT. Idempotent per `send:{chatId}:{messageId}` (00-master-spec.md §4).
- [Get a run's current status, including its tool invocations](https://docs.vyomflow.co.in/api-reference/runs/get-a-runs-current-status-including-its-tool-invocations.md)
- [Cancel an active run](https://docs.vyomflow.co.in/api-reference/runs/cancel-an-active-run.md): Cascades cancellation to in-flight children; a media-processing task already in flight cannot itself be cancelled remotely, so a background reconciliation sweep later captures its true final cost (00-master-spec.md §4 scenario 7).
- [Mint a fresh Trigger.dev realtime access token for this run](https://docs.vyomflow.co.in/api-reference/runs/mint-a-fresh-triggerdev-realtime-access-token-for-this-run.md): Trigger.dev public access tokens default to a 15-minute expiry; this endpoint is the mandatory refresh path for turns that run longer than that (00-master-spec.md §8).
- [Respond to a pending CREDIT_APPROVAL or CLARIFICATION waitpoint](https://docs.vyomflow.co.in/api-reference/waitpoints/respond-to-a-pending-credit_approval-or-clarification-waitpoint.md): Resumes the suspended run. A duplicate response to an already-`COMPLETED`/`EXPIRED` waitpoint is a no-op guarded on `Waitpoint.status` (00-master-spec.md §4 scenario 9).
- [Get the caller's credit balance](https://docs.vyomflow.co.in/api-reference/credits/get-the-callers-credit-balance.md): available = balance - held, computed at read time — never a stored/cached value.
- [List the caller's credit ledger, optionally filtered to one tool bucket](https://docs.vyomflow.co.in/api-reference/credits/list-the-callers-credit-ledger-optionally-filtered-to-one-tool-bucket.md): Cursor-paginated, net-`CAPTURE`/`USAGE`-only rows (`RESERVE`/`RELEASE` are hold-lifecycle bookkeeping, excluded here — see `/ledger/run/{runId}` for the full raw lifecycle).
- [Get the caller's real per-tool credit usage aggregation](https://docs.vyomflow.co.in/api-reference/credits/get-the-callers-real-per-tool-credit-usage-aggregation.md): A `GROUP BY toolInvocation.name` aggregation over `CreditLedger` CAPTURE/USAGE rows — backs the /usage dashboard's stat cards and Overview tab.
- [List the caller's netted usage entries for one tool bucket](https://docs.vyomflow.co.in/api-reference/credits/list-the-callers-netted-usage-entries-for-one-tool-bucket.md): One row per run within the requested tool bucket (backs the /usage Detailed View tab's record table) — `amount` is that run's CAPTURE/USAGE total, never RESERVE/RELEASE.
- [Get one run's full raw credit-ledger step breakdown](https://docs.vyomflow.co.in/api-reference/credits/get-one-runs-full-raw-credit-ledger-step-breakdown.md): Every `CreditLedger` row sharing this run's `runId` — the full RESERVE/CAPTURE/RELEASE/USAGE lifecycle, not just the net-debited subset — backs the /usage "Usage details" modal. Caller-scoped: a runId belonging to another user returns an empty `items`/`null` chatId, never a 404/403 leak of whether t…
- [Mint signed Transloadit assembly parameters for a resumable direct upload](https://docs.vyomflow.co.in/api-reference/attachments/mint-signed-transloadit-assembly-parameters-for-a-resumable-direct-upload.md)
- [List the caller's media-library attachments (cursor-paginated)](https://docs.vyomflow.co.in/api-reference/attachments/list-the-callers-media-library-attachments-cursor-paginated.md)
- [Mark a direct upload complete once the Transloadit assembly finishes](https://docs.vyomflow.co.in/api-reference/attachments/mark-a-direct-upload-complete-once-the-transloadit-assembly-finishes.md)
- [Cancel a mid-upload attachment, or permanently delete an unbound one](https://docs.vyomflow.co.in/api-reference/attachments/cancel-a-mid-upload-attachment-or-permanently-delete-an-unbound-one.md): Cancels a PENDING upload, or permanently deletes a READY/FAILED/CANCELLED unbound row otherwise — never a row already bound to a sent message. Returns the resulting attachment, not an empty body.
- [Set (or rotate) the caller's outbound webhook endpoint](https://docs.vyomflow.co.in/api-reference/webhooks/set-or-rotate-the-callers-outbound-webhook-endpoint.md): One `WebhookEndpoint` row per user. First call creates it and returns a server-generated `secret` in plaintext (the only time it is ever shown again). A later call without `rotateSecret` just updates `url`; `rotateSecret: true` moves the current secret into `secondarySecret` (kept valid for a grace…
- [Mint a self-serve public-API key](https://docs.vyomflow.co.in/api-reference/api-keys/mint-a-self-serve-public-api-key.md): Creates a new API key for the caller, scoped to the fixed default set of public-API scopes. The `secret` is returned in plaintext only on this response and cannot be retrieved again afterward.
- [List the caller's chats (cursor-paginated, newest first)](https://docs.vyomflow.co.in/api-reference/public-api/list-the-callers-chats-cursor-paginated-newest-first.md)
- [Create a chat](https://docs.vyomflow.co.in/api-reference/public-api/create-a-chat.md)
- [List a chat's messages (cursor-paginated)](https://docs.vyomflow.co.in/api-reference/public-api/list-a-chats-messages-cursor-paginated.md)
- [Submit a message and start (or continue) an agent turn](https://docs.vyomflow.co.in/api-reference/public-api/submit-a-message-and-start-or-continue-an-agent-turn.md): Same Turn Lifecycle as the internal route, plus an optional `Idempotency-Key` header — a retried request presenting the same key for this chat replays the original turn's current state rather than charging credits or dispatching twice. Response omits the raw Trigger.dev realtime token; `stream.url`…
- [Get a run's current status, including its tool invocations](https://docs.vyomflow.co.in/api-reference/public-api/get-a-runs-current-status-including-its-tool-invocations.md)
- [Subscribe to a run's live event stream (SSE)](https://docs.vyomflow.co.in/api-reference/public-api/subscribe-to-a-runs-live-event-stream-sse.md): text/event-stream, not JSON — the individual event shapes are Zod-defined in src/contracts/public-events.ts and documented in full on the streaming guide, since SSE cannot be expressed as an OpenAPI response schema. Resume with the standard `Last-Event-ID` header; never pass the API key as a query p…
- [Cancel an active run](https://docs.vyomflow.co.in/api-reference/public-api/cancel-an-active-run.md)
- [Respond to a pending CREDIT_APPROVAL or CLARIFICATION waitpoint](https://docs.vyomflow.co.in/api-reference/public-api/respond-to-a-pending-credit_approval-or-clarification-waitpoint.md): Idempotent — a repeat call on an already-resolved waitpoint still returns 200 with the current DTO, never an error.
- [Get the caller's credit balance](https://docs.vyomflow.co.in/api-reference/public-api/get-the-callers-credit-balance.md): available = balance - held, computed at read time — never a stored/cached value.

## OpenAPI Specs

- [openapi](/openapi.json)