# 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 in under 5 minutes: create a chat, send a message, and stream the agent response.
- [Authenticate Requests to the VyomFlow API](https://docs.vyomflow.co.in/authentication.md): Every VyomFlow API request requires a Clerk session bearer token passed in the Authorization header.
- [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.
- [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 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)
- [Permanently delete a media-library attachment](https://docs.vyomflow.co.in/api-reference/attachments/permanently-delete-a-media-library-attachment.md)

## OpenAPI Specs

- [openapi](/openapi.json)