# Timbal

- [Introduction](https://docs.timbal.ai/index.md): Simple, performant, battle-tested framework for building reliable AI applications
- [Installation](https://docs.timbal.ai/installation.md): Step-by-step instructions for setting up Timbal CLI and Python package
- [Quickstart](https://docs.timbal.ai/quickstart.md): Build your first AI Agent with Timbal in a few lines of code
- [Runnables](https://docs.timbal.ai/core-concepts/runnables.md): Executable primitives that provide consistent interfaces for all Timbal components
- [Events & Streaming](https://docs.timbal.ai/core-concepts/events.md): Monitor execution in real-time and handle streaming results
- [Tracing & Observability](https://docs.timbal.ai/core-concepts/tracing.md): Comprehensive execution tracing with input/output/error/timing capture for complete observability
- [Context & State Management](https://docs.timbal.ai/core-concepts/context.md): The shared memory that connects everything together across the entire lifetime of a run
- [Overview](https://docs.timbal.ai/agents/index.md): Master proven strategies for designing advanced, specialized AI agents using an architecture that work together seamlessly to tackle complex challenges
- [Adding Tools](https://docs.timbal.ai/agents/tools.md): Give your agents the ability to interact with the outside world through automatic schema generation, parameter validation, and concurrent execution
- [MCP Servers](https://docs.timbal.ai/agents/mcp.md): Connect any Model Context Protocol server to your agents and use its tools like native Timbal tools
- [Structured Output](https://docs.timbal.ai/agents/structured-output.md): Use Pydantic models to structure and validate your agent outputs
- [Memory](https://docs.timbal.ai/agents/memory.md): Understand and manage how Agent memory works
- [Memory Compaction](https://docs.timbal.ai/agents/memory-compaction.md): Keep agent memory within context window limits with tool result offloading and built-in compaction strategies
- [Guardrails](https://docs.timbal.ai/agents/guardrails.md): Content policy for the four edges of an agent run: input, model output, tool args, and tool results
- [Skills](https://docs.timbal.ai/agents/skills.md): Extend Agent capabilities through dynamic discovery of knowledge and tools
- [Dynamic Agents](https://docs.timbal.ai/agents/dynamic.md): Learn how to create agents with dynamic system prompts that update automatically using real time data
- [Background Tasks](https://docs.timbal.ai/agents/background-tasks.md): Execute long-running operations asynchronously
- [Commands](https://docs.timbal.ai/agents/commands.md): Invoke tools, agents, and workflows directly with slash commands — no LLM round-trip
- [Voice Agents](https://docs.timbal.ai/voice/index.md): Build live spoken conversations with streaming transcription, agents, tools, and speech output
- [Your First Voice Agent](https://docs.timbal.ai/voice/quickstart.md): Run a live voice agent locally and talk to it in the browser
- [Greetings](https://docs.timbal.ai/voice/greetings.md): Start with a fixed hello, then control when the opener plays and how it is generated
- [Using Tools](https://docs.timbal.ai/voice/tools.md): Give a spoken assistant a function and hear it answer from the result
- [Thinking Sounds](https://docs.timbal.ai/voice/thinking-sounds.md): Play a quiet browser sound while a tool is running
- [Spoken Fillers](https://docs.timbal.ai/voice/fillers.md): Have the assistant acknowledge a slow tool call with a short spoken phrase
- [Background Audio](https://docs.timbal.ai/voice/background-audio.md): Add a quiet continuous ambience track to the browser conversation
- [Turn-Taking and Interruptions](https://docs.timbal.ai/voice/turn-taking.md): Test pauses and interruptions before tuning end-of-turn detection
- [Silence and Timeouts](https://docs.timbal.ai/voice/silence.md): Add an idle check-in, then bound quiet calls and slow turns
- [Recording Calls](https://docs.timbal.ai/voice/recording.md): Save a conversation locally, then separate caller and assistant channels
- [Voice Transports](https://docs.timbal.ai/voice/transports.md): Connect browser clients, WebRTC, LiveKit rooms, and Twilio or Telnyx phone calls
- [Voice Events and Usage](https://docs.timbal.ai/voice/observability.md): Inspect transcripts, response latency, provider-reported usage, and call recordings
- [Providers and Configuration](https://docs.timbal.ai/voice/configuration.md): Reference for speech providers, audio formats, configuration inheritance, and operator defaults
- [Custom Voice Pipelines](https://docs.timbal.ai/voice/custom-pipelines.md): Embed VoiceSession in your application and implement custom speech adapters
- [Overview](https://docs.timbal.ai/workflows/index.md): Build multi-step AI pipelines with explicit control flow
- [Control Flow](https://docs.timbal.ai/workflows/control-flow.md): Manage step execution order with dependencies and data passing
- [Branching](https://docs.timbal.ai/workflows/branching.md): Conditional step execution with the `when` parameter
- [Errors & Failure](https://docs.timbal.ai/workflows/errors-and-failure.md): How workflow steps fail, skip, and propagate errors
- [Agents & LLMs](https://docs.timbal.ai/workflows/agents-and-llms.md): Use Agents as workflow steps and build LLM routing pipelines
- [Human in the Loop](https://docs.timbal.ai/workflows/human-in-the-loop.md): Pause workflow steps for approval or user input, then resume
- [Sequential Steps](https://docs.timbal.ai/examples/workflows/sequential-steps.md): Chain multiple processing steps with data passing between them
- [Parallel Fan-Out](https://docs.timbal.ai/examples/workflows/parallel-fan-out.md): Fetch data from multiple sources in parallel and merge the results
- [Conditional Routing](https://docs.timbal.ai/examples/workflows/conditional-routing.md): Process data differently based on validation results
- [Workflow Composition](https://docs.timbal.ai/examples/workflows/workflow-composition.md): Nest workflows inside other workflows for modular pipelines
- [Overview](https://docs.timbal.ai/human-in-the-loop/index.md): Pause any run for a human: gate irreversible actions for approval, or stop mid-handler to ask the user a question, then resume on the same durable rails
- [Approval gates](https://docs.timbal.ai/human-in-the-loop/approval-gates.md): Declarative permission checks that fire before a runnable executes — gate irreversible actions for human approval
- [Suspend & interaction tools](https://docs.timbal.ai/human-in-the-loop/suspend.md): Pause a run from inside a handler to ask the user for arbitrary input, then resume with their answer
- [Resuming a paused run](https://docs.timbal.ai/human-in-the-loop/resuming.md): Resume any paused run (gate or suspension) with parent_id and resume={...}, in-process or across workers
- [Client integration (HTTP)](https://docs.timbal.ai/human-in-the-loop/client-integration.md): The full contract for a frontend talking to the /stream SSE endpoint: pause, render, resume
- [Observability](https://docs.timbal.ai/human-in-the-loop/observability.md): Status reasons, usage counters, and common patterns for paused runs
- [Overview](https://docs.timbal.ai/evals/index.md): Automated testing framework for Timbal agents and runnables
- [Writing Evals](https://docs.timbal.ai/evals/writing-evals.md): Learn how to write effective evals for your Timbal agents
- [Overview](https://docs.timbal.ai/evals/validators/index.md): Complete reference for all Timbal eval validators
- [Comparison Validators](https://docs.timbal.ai/evals/validators/comparison.md): Validators for equality, containment, patterns, and numeric comparisons
- [Type Validators](https://docs.timbal.ai/evals/validators/type.md): Validators for type checking, JSON, email, and null validation
- [Length Validators](https://docs.timbal.ai/evals/validators/length.md): Validators for checking length constraints on strings, lists, and collections
- [LLM Validators](https://docs.timbal.ai/evals/validators/llm.md): AI-powered validators for checking claims, meaning, and language
- [Flow Validators](https://docs.timbal.ai/evals/validators/flow.md): Validators for checking execution sequences and parallel execution
- [Running Evals](https://docs.timbal.ai/evals/running-evals.md): CLI usage, file discovery, and CI/CD integration
- [Overview](https://docs.timbal.ai/deployment/index.md): Run and deploy Timbal projects locally or in production
- [Timbal Platform](https://docs.timbal.ai/deployment/platform.md): Deploy Timbal projects to managed hosting
- [Self-Hosted](https://docs.timbal.ai/deployment/self-hosted.md): Run Timbal projects on your own infrastructure
- [Overview](https://docs.timbal.ai/examples/index.md): Complete guides and building patterns for Timbal AI agents
- [Mail Assistant](https://docs.timbal.ai/examples/guides/mail-assistant.md): AI-powered Gmail integration that triages emails and autonomously drafts intelligent responses
- [Slack Bot](https://docs.timbal.ai/examples/guides/slack-bot.md): Build a Slack bot that responds in real time via webhooks, with an AI agent and threaded conversations
- [WhatsApp Assistant](https://docs.timbal.ai/examples/guides/whatsapp-assistant.md): Build a text WhatsApp assistant with webhooks and conversation persistence, then extend it to media
- [Images](https://docs.timbal.ai/examples/agents/images.md): AI agents can analyze and understand images by processing visual content alongside text instructions
- [Word](https://docs.timbal.ai/examples/agents/docx.md): AI agents can read and analyze Microsoft Word documents for content extraction and processing
- [CSV](https://docs.timbal.ai/examples/agents/csv.md): AI agents can analyze and process CSV data files for insights and data manipulation
- [PDF](https://docs.timbal.ai/examples/agents/pdf.md): AI agents can read and analyze PDF documents for content extraction and processing
- [Email](https://docs.timbal.ai/examples/agents/emls.md): AI agents can process and summarize email files for quick content extraction and analysis
- [Audio](https://docs.timbal.ai/examples/agents/audio.md): AI agents can process audio files for transcription and analysis using speech-to-text capabilities
- [Web Search](https://docs.timbal.ai/examples/agents/search.md): Use provider-native web search or an executable search service with any tool-capable model
- [Text-to-Speech](https://docs.timbal.ai/examples/agents/tts.md): Generate audio with text-to-speech tools or use OpenAI and Deepgram in live voice sessions
- [Image Generation](https://docs.timbal.ai/examples/agents/image-generation.md): AI agents can generate images from text descriptions using OpenAI's image generation tools
- [Asking the User](https://docs.timbal.ai/examples/agents/ask-user.md): Interaction tools built on suspend() — free text, single/multi choice, confirmation, structured forms, ratings, uploads, and generative-UI review — each with its own payload shape
- [Approval-Required Tools](https://docs.timbal.ai/examples/agents/approval-required-tools.md): Pause an agent for human approval, capture the gate, and resume with a decision — including redaction and audit fields
- [SQL Queries and Data Management](https://docs.timbal.ai/examples/agents/sql-queries.md): Expose parameterized knowledge-base queries and explicit data operations as agent tools
- [Semantic and Hybrid Search](https://docs.timbal.ai/examples/agents/semantic-search.md): Give an agent a parameterized search tool over an existing Timbal knowledge base
- [Custom Functions in System Prompts](https://docs.timbal.ai/examples/agents/custom-functions-system-prompts.md): Use your own functions to build dynamic system prompts that include real-time data and custom logic
- [Adaptive System Prompts](https://docs.timbal.ai/examples/agents/adaptive-system-prompts.md): Adapt agent behavior based on detected context or origin
- [Content-Aware Tools](https://docs.timbal.ai/examples/agents/content-aware-tools.md): Use ToolSet to resolve tools dynamically based on content type - automatically select image or PDF tools
- [Input Parameters](https://docs.timbal.ai/examples/agents/input-validation.md): Pass input parameters to agents and validate the output response
- [Output Validation](https://docs.timbal.ai/examples/agents/output-validation.md): Validate agent responses using content checks, format validation, and semantic evaluation
- [Execution Behavior](https://docs.timbal.ai/examples/agents/execution-behavior.md): Validate agent execution flow, tool usage, and sequence of operations
- [Multi-turn Conversations](https://docs.timbal.ai/examples/agents/multi-turn-conversation.md): Test agent memory, context retention, and complex conversational flows across multiple interactions
- [Sequential Steps](https://docs.timbal.ai/examples/workflows/sequential-steps.md): Chain multiple processing steps with data passing between them
- [Conditional Routing](https://docs.timbal.ai/examples/workflows/conditional-routing.md): Process data differently based on validation results
- [Parallel Fan-Out](https://docs.timbal.ai/examples/workflows/parallel-fan-out.md): Fetch data from multiple sources in parallel and merge the results
- [Workflow Composition](https://docs.timbal.ai/examples/workflows/workflow-composition.md): Nest workflows inside other workflows for modular pipelines
- [Introduction](https://docs.timbal.ai/api-reference/introduction.md): Introduction to the Timbal Platform API
- [Authentication](https://docs.timbal.ai/api-reference/authentication.md): How to authenticate to the Timbal API
- [Errors](https://docs.timbal.ai/api-reference/errors.md): How to handle errors
- [Pagination](https://docs.timbal.ai/api-reference/pagination.md): How to paginate through resources
- [Upload file (temporary)](https://docs.timbal.ai/api-reference/files/upload.md): Upload a short-lived file for temporary staging.
- [List Organizations](https://docs.timbal.ai/api-reference/me/list-orgs.md): List organizations the authenticated user belongs to
- [Update Profile](https://docs.timbal.ai/api-reference/me/update.md): Patch the authenticated user's profile.
- [Upload Profile Photo](https://docs.timbal.ai/api-reference/me/photo/upload.md): Upload and set the authenticated user's profile picture.
- [Delete Profile Photo](https://docs.timbal.ai/api-reference/me/photo/delete.md): Clear the authenticated user's profile picture.
- [List API Tokens](https://docs.timbal.ai/api-reference/me/tokens/list.md): List the authenticated user's API credentials.
- [Create API Token](https://docs.timbal.ai/api-reference/me/tokens/create.md): Create an API credential for the authenticated user.
- [Revoke API Token](https://docs.timbal.ai/api-reference/me/tokens/revoke.md): Revoke an API credential owned by the authenticated user.
- [Create Organization](https://docs.timbal.ai/api-reference/orgs/create.md): Create a new organization.
- [Get Organization](https://docs.timbal.ai/api-reference/orgs/get.md): Get an organization by ID
- [Update Organization](https://docs.timbal.ai/api-reference/orgs/update.md): Partially update an organization
- [List Account Contacts](https://docs.timbal.ai/api-reference/orgs/contacts/list.md): Account-side contacts assigned to an organization.
- [List Embedding Models](https://docs.timbal.ai/api-reference/orgs/embedding-models/list.md): List all available embedding models for the organization
- [Org Analytics — Costs](https://docs.timbal.ai/api-reference/orgs/analytics/costs.md): Time-binned credits and USD spend across an org, grouped by product surface.
- [Org Analytics — Usage](https://docs.timbal.ai/api-reference/orgs/analytics/usage.md): Time-binned run counts, user counts, and duration percentiles across an org.
- [Org Analytics — Users](https://docs.timbal.ai/api-reference/orgs/analytics/users.md): Per-user run counts and full-ledger spend aggregates across an org.
- [Get Overage Summary](https://docs.timbal.ai/api-reference/orgs/billing/overage-summary.md): Get overage credit usage for the current billing period.
- [Update Overage Billing](https://docs.timbal.ai/api-reference/orgs/billing/overage.md): Update overage billing settings for the organization.
- [Get Credit Budgets](https://docs.timbal.ai/api-reference/orgs/billing/budgets/get.md): Read credit budgets for the organization.
- [Replace Credit Budgets](https://docs.timbal.ai/api-reference/orgs/billing/budgets/replace.md): Replace the organization's full credit budget configuration.
- [Patch Credit Budgets](https://docs.timbal.ai/api-reference/orgs/billing/budgets/patch.md): Merge partial credit budget changes for the organization.
- [Get Compute Billing](https://docs.timbal.ai/api-reference/orgs/billing/compute/get.md): Get purchased compute machines and the org's compute pool usage.
- [Set Compute Billing](https://docs.timbal.ai/api-reference/orgs/billing/compute/put.md): Set the compute machine add-ons purchased by the organization.
- [Sign Content URL](https://docs.timbal.ai/api-reference/orgs/content/sign.md): Refresh a signed URL for stored content.
- [Upload Organization Logo](https://docs.timbal.ai/api-reference/orgs/photo/upload.md): Upload and set the organization's logo.
- [Delete Organization Logo](https://docs.timbal.ai/api-reference/orgs/photo/delete.md): Clear the organization's logo.
- [List Credit Grants](https://docs.timbal.ai/api-reference/orgs/credit-grants/list.md): Credit grants awarded to an organization, most recent first.
- [List Model Policies](https://docs.timbal.ai/api-reference/orgs/models/policies/list.md): List the organization's LLM model and provider usage policies.
- [Create Model Policy](https://docs.timbal.ai/api-reference/orgs/models/policies/create.md): Create a rule restricting which LLM providers or models the organization can use.
- [Delete Model Policy](https://docs.timbal.ai/api-reference/orgs/models/policies/delete.md): Delete an LLM model or provider policy rule from the organization.
- [List Templates](https://docs.timbal.ai/api-reference/orgs/templates/list.md): Public project template catalog available to this organization.
- [List Domains](https://docs.timbal.ai/api-reference/orgs/domains/list.md): List connected domains for an organization
- [Create Domain](https://docs.timbal.ai/api-reference/orgs/domains/create.md): Add a custom domain to an organization
- [Get Domain](https://docs.timbal.ai/api-reference/orgs/domains/get.md): Get a custom domain with current DNS and certificate status.
- [Delete Domain](https://docs.timbal.ai/api-reference/orgs/domains/delete.md): Delete a domain
- [List IAM Actions](https://docs.timbal.ai/api-reference/orgs/iam/actions/list.md): Catalog of grantable IAM actions for the organization.
- [List Users by Action](https://docs.timbal.ai/api-reference/orgs/iam/actions/users.md): List members who effectively hold an org-wide IAM action.
- [List Users by Resource](https://docs.timbal.ai/api-reference/orgs/iam/resources/users.md): List members with effective access to a resource, per action.
- [Check IAM Permissions](https://docs.timbal.ai/api-reference/orgs/iam/check.md): Simulate authorization checks against a user's effective grants.
- [List Organization Roles](https://docs.timbal.ai/api-reference/orgs/roles/list.md): List system and custom roles for the organization.
- [Create Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/create.md): Create a custom role for the organization.
- [Get Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/get.md): Retrieve a role and the full set of grants it carries.
- [Update Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/update.md): Partially update a custom organization role.
- [Delete Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/delete.md): Delete a custom organization role.
- [List Users](https://docs.timbal.ai/api-reference/orgs/users/list.md): List members of an organization.
- [Add User](https://docs.timbal.ai/api-reference/orgs/users/add.md): Invite one or more users to an organization
- [Remove User](https://docs.timbal.ai/api-reference/orgs/users/delete.md): Remove one or more members from an organization
- [Update User Roles](https://docs.timbal.ai/api-reference/orgs/users/update.md): Replace a member's role attachments.
- [Batch Update User Roles](https://docs.timbal.ai/api-reference/orgs/iam/users/batch-roles.md): Replace role attachments for multiple members in one request.
- [Get User Effective Grants](https://docs.timbal.ai/api-reference/orgs/iam/users/effective-grants.md): List a member's effective IAM grants in the organization.
- [List Identity Providers](https://docs.timbal.ai/api-reference/orgs/identity-providers/list.md): List SSO identity connections for the organization.
- [Create Identity Provider](https://docs.timbal.ai/api-reference/orgs/identity-providers/create.md): Create an SSO or directory identity connection for the organization.
- [Get a single SSO connection (secret masked)](https://docs.timbal.ai/api-reference/orgs/identity-providers/get.md): Get an SSO identity connection by id.
- [Update Identity Provider](https://docs.timbal.ai/api-reference/orgs/identity-providers/update.md): Update an SSO identity connection.
- [Delete an SSO connection (cascades to its group mappings)](https://docs.timbal.ai/api-reference/orgs/identity-providers/delete.md): Delete an SSO identity connection.
- [Default Role](https://docs.timbal.ai/api-reference/orgs/identity-providers/default-role.md): Set or clear the SSO connection's default just-in-time role.
- [List external-group to role mappings for a connection](https://docs.timbal.ai/api-reference/orgs/identity-providers/group-mappings/list.md): List external-group to role mappings for a connection
- [Map an external IdP group to a role for this connection](https://docs.timbal.ai/api-reference/orgs/identity-providers/group-mappings/create.md): Map an external IdP group to a role for this connection
- [Delete a group-to-role mapping](https://docs.timbal.ai/api-reference/orgs/identity-providers/group-mappings/delete.md): Delete a group-to-role mapping
- [List SCIM Tokens](https://docs.timbal.ai/api-reference/orgs/scim-tokens/list.md): List SCIM tokens for the organization.
- [Create SCIM Token](https://docs.timbal.ai/api-reference/orgs/scim-tokens/create.md): Create a SCIM bearer token for the organization.
- [Revoke SCIM Token](https://docs.timbal.ai/api-reference/orgs/scim-tokens/revoke.md): Revoke a SCIM token
- [List Projects](https://docs.timbal.ai/api-reference/projects/list.md): List projects in an organization.
- [Create Project](https://docs.timbal.ai/api-reference/projects/create.md): Create a new project.
- [Get Project](https://docs.timbal.ai/api-reference/projects/get.md): Get a project by ID.
- [Update Project](https://docs.timbal.ai/api-reference/projects/update.md): Edit project metadata.
- [Delete Project](https://docs.timbal.ai/api-reference/projects/delete.md): Delete a project.
- [Duplicate Project](https://docs.timbal.ai/api-reference/projects/duplicate.md): Duplicate a project, copying its code and knowledge base structure.
- [Link Knowledge Base](https://docs.timbal.ai/api-reference/projects/link-knowledge-base.md): Link a knowledge base to a project.
- [Unlink Knowledge Base](https://docs.timbal.ai/api-reference/projects/unlink-knowledge-base.md): Unlink the knowledge base from a project.
- [Get App Auth Settings](https://docs.timbal.ai/api-reference/projects/auth/get.md): Get app sign-in settings for a project.
- [Update App Auth Settings](https://docs.timbal.ai/api-reference/projects/auth/update.md): Toggle app sign-in for a project.
- [Update Auth Provider](https://docs.timbal.ai/api-reference/projects/auth/providers/update.md): Enable, disable, or configure an app sign-in provider.
- [Cost Analytics](https://docs.timbal.ai/api-reference/projects/analytics/credits.md): Time-binned credits and USD cost breakdown for a project.
- [Usage Analytics](https://docs.timbal.ai/api-reference/projects/analytics/usage.md): Time-binned run counts, user counts, and duration percentiles for a project.
- [User Analytics](https://docs.timbal.ai/api-reference/projects/analytics/users.md): Per-user run counts and project-attributed spend aggregates for a project.
- [List Environments](https://docs.timbal.ai/api-reference/projects/environments/list.md): List environments for a project with resolved per-component deploy config.
- [Create Environment](https://docs.timbal.ai/api-reference/projects/environments/create.md): Create a new environment for a project.
- [Delete Environment](https://docs.timbal.ai/api-reference/projects/environments/delete.md): Delete an environment.
- [Update Branch](https://docs.timbal.ai/api-reference/projects/environments/update-branch.md): Set or clear the source branch for an environment.
- [Update Config](https://docs.timbal.ai/api-reference/projects/environments/update-config.md): Update deploy configuration for an environment, including per-component overrides.
- [Deploy](https://docs.timbal.ai/api-reference/projects/environments/deploy.md): Deploy an environment to a revision.
- [Update Domain](https://docs.timbal.ai/api-reference/projects/environments/update-domain.md): Attach, replace, or detach a custom domain for an environment.
- [Get Metrics](https://docs.timbal.ai/api-reference/projects/environments/get-metrics.md): Query runtime metrics for an environment.
- [Stop](https://docs.timbal.ai/api-reference/projects/environments/stop.md): Stop a running environment.
- [List Environment Deployments](https://docs.timbal.ai/api-reference/projects/environments/deployments/list.md): List deployments for an environment.
- [Get Environment Logs](https://docs.timbal.ai/api-reference/projects/environments/logs.md): Fetch runtime logs for a deployed project component.
- [List Runs](https://docs.timbal.ai/api-reference/projects/runs/list.md): List runs for a project.
- [Get Run](https://docs.timbal.ai/api-reference/projects/runs/get.md): Get a single project run by id or idempotency key.
- [List Reactions](https://docs.timbal.ai/api-reference/projects/runs/reactions-list.md): List reactions on a project run.
- [Add Reaction](https://docs.timbal.ai/api-reference/projects/runs/reactions-add.md): Add a reaction to a project run.
- [List Variables](https://docs.timbal.ai/api-reference/projects/vars/list.md): List variables for a project.
- [Create Variable](https://docs.timbal.ai/api-reference/projects/vars/create.md): Create a project variable.
- [Batch Create Variables](https://docs.timbal.ai/api-reference/projects/vars/batch-create.md): Batch create project variables.
- [Get Variable](https://docs.timbal.ai/api-reference/projects/vars/get.md): Get a project variable by ID.
- [Delete Variable](https://docs.timbal.ai/api-reference/projects/vars/delete.md): Delete a project variable.
- [Update Variable](https://docs.timbal.ai/api-reference/projects/vars/update.md): Update a project variable.
- [Upsert Channel](https://docs.timbal.ai/api-reference/projects/channels/put.md): Connect or update a messaging channel binding. Upserts on (workforce, provider); `credentials` is write-only — omit to keep the stored secrets, `null` to clear them, an object to replace them.
- [Delete Channel](https://docs.timbal.ai/api-reference/projects/channels/delete.md): Disconnect a messaging channel binding, discarding its stored credentials.
- [List Workforce](https://docs.timbal.ai/api-reference/projects/workforce/list.md): List workforce components on a branch revision.
- [Create Workforce](https://docs.timbal.ai/api-reference/projects/workforce/create.md): Create a workforce component on a branch revision.
- [Delete Workforce](https://docs.timbal.ai/api-reference/projects/workforce/delete.md): Delete a workforce component on a branch revision.
- [Call Workforce](https://docs.timbal.ai/api-reference/projects/workforce/call.md): Proxy HTTP requests to a deployed workforce component.
- [Call Workforce (GET)](https://docs.timbal.ai/api-reference/projects/workforce/call-get.md): Proxy HTTP requests to a deployed workforce component.
- [Call Workforce (PUT)](https://docs.timbal.ai/api-reference/projects/workforce/call-put.md): Proxy HTTP requests to a deployed workforce component.
- [Call Workforce (PATCH)](https://docs.timbal.ai/api-reference/projects/workforce/call-patch.md): Proxy HTTP requests to a deployed workforce component.
- [Call Workforce (DELETE)](https://docs.timbal.ai/api-reference/projects/workforce/call-delete.md): Proxy HTTP requests to a deployed workforce component.
- [List Knowledge Bases](https://docs.timbal.ai/api-reference/knowledge-bases/list.md): List knowledge bases in an organization
- [Create Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/create.md): Create a new knowledge base
- [Get Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/get.md): Get knowledge base details
- [Edit Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/update.md): Update a knowledge base.
- [Delete Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/delete.md): Delete a knowledge base
- [Query](https://docs.timbal.ai/api-reference/knowledge-bases/query.md): Execute a SQL query against the knowledge base
- [Get Schema](https://docs.timbal.ai/api-reference/knowledge-bases/schema.md): Get the schema for a knowledge base
- [Upload Data](https://docs.timbal.ai/api-reference/knowledge-bases/upload.md): Upload a data file into a knowledge base.
- [List Policies](https://docs.timbal.ai/api-reference/knowledge-bases/policies/list.md): List access-shaping rules authored on a knowledge base.
- [Create Policy](https://docs.timbal.ai/api-reference/knowledge-bases/policies/create.md): Author a new access-shaping rule on a knowledge base.
- [Get Policy](https://docs.timbal.ai/api-reference/knowledge-bases/policies/get.md): Fetch a single access-shaping rule by id.
- [Update Policy](https://docs.timbal.ai/api-reference/knowledge-bases/policies/update.md): Update an access-shaping rule on a knowledge base.
- [Delete Policy](https://docs.timbal.ai/api-reference/knowledge-bases/policies/delete.md): Soft-delete an access-shaping rule on a knowledge base.
- [Set Governance Mode](https://docs.timbal.ai/api-reference/knowledge-bases/policies/governance-mode.md): Set query-time governance mode for a knowledge base.
- [List Policy Assignments](https://docs.timbal.ai/api-reference/knowledge-bases/policies/assignments/list.md): List role bindings for an access-shaping rule.
- [Create Policy Assignment](https://docs.timbal.ai/api-reference/knowledge-bases/policies/assignments/create.md): Bind an access-shaping rule to a role.
- [Get Policy Assignment](https://docs.timbal.ai/api-reference/knowledge-bases/policies/assignments/get.md): Fetch a single role binding for an access-shaping rule.
- [Delete Policy Assignment](https://docs.timbal.ai/api-reference/knowledge-bases/policies/assignments/delete.md): Revoke a role binding on an access-shaping rule.
- [List Backups](https://docs.timbal.ai/api-reference/knowledge-bases/backups/list.md): List backups for a knowledge base.
- [Create Backup](https://docs.timbal.ai/api-reference/knowledge-bases/backups/create.md): Create an on-demand backup of a knowledge base.
- [Get Backup](https://docs.timbal.ai/api-reference/knowledge-bases/backups/get.md): Get a single backup.
- [List Restores](https://docs.timbal.ai/api-reference/knowledge-bases/restores/list.md): List restore attempts for a knowledge base.
- [Restore](https://docs.timbal.ai/api-reference/knowledge-bases/restores/create.md): Restore a knowledge base from a completed backup.
- [Get Restore](https://docs.timbal.ai/api-reference/knowledge-bases/restores/get.md): Get a single restore.
- [List Files](https://docs.timbal.ai/api-reference/knowledge-bases/files/list.md): List files and folders in a knowledge base directory.
- [Add File](https://docs.timbal.ai/api-reference/knowledge-bases/files/add.md): Add a file to a knowledge base by upload or URL.
- [Create Directory](https://docs.timbal.ai/api-reference/knowledge-bases/files/create-dir.md): Create a virtual directory in the knowledge base
- [Get File](https://docs.timbal.ai/api-reference/knowledge-bases/files/get.md): Get a file with its parsings and embeddings metadata
- [Delete File](https://docs.timbal.ai/api-reference/knowledge-bases/files/delete.md): Delete a file from a knowledge base
- [List Chunks](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/list.md): List chunks for a knowledge base file in document order.
- [Insert Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/insert.md): Insert a new chunk into a knowledge base file.
- [Get Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/get.md): Get a single chunk by uid.
- [Update Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/update.md): Edit a chunk's content, embedding, or page range.
- [Delete Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/delete.md): Delete a chunk from a knowledge base file.
- [List Eval Definitions](https://docs.timbal.ai/api-reference/evals/definitions.md): List eval definitions (test cases from evals/*.yaml) per workforce component. Reads the env branch's worktree by default; pass ?rev= to read from git.
- [List Eval Jobs](https://docs.timbal.ai/api-reference/evals/jobs/list.md): List eval jobs (background eval generation) for an env, most recent first.
- [Get Eval Job](https://docs.timbal.ai/api-reference/evals/jobs/get.md): Get a single eval job by uid.
- [Create Eval Job](https://docs.timbal.ai/api-reference/evals/jobs/create.md): Enqueue a background eval job (today: generate_initial — Claude-generate an initial eval suite for a workforce component, written to the env branch's worktree).
- [List Eval Runs](https://docs.timbal.ai/api-reference/evals/runs/list.md): List eval runs (deploy-gate and manual executions) for an environment.
- [Get Eval Run](https://docs.timbal.ai/api-reference/evals/runs/get.md): Get a single eval run, including its logs.
- [Stream Eval Run Events](https://docs.timbal.ai/api-reference/evals/runs/events.md): Stream an in-flight eval run's JSONL events (cursor + long-poll). On `expired: true`, fall back to the single-run GET.
- [Create Eval Run](https://docs.timbal.ai/api-reference/evals/runs/create.md): Manually run evals for a workforce component (no deploy). Defaults to the env worktree so uncommitted evals are included; pass source=git for a clean extract.
- [Delete Eval Run](https://docs.timbal.ai/api-reference/evals/runs/delete.md): Delete an eval run from the history. Running runs cannot be deleted.
- [Create from Agent](https://docs.timbal.ai/api-reference/ace/create-from-workforce.md): Create an empty ACE (ready, empty playbook) and link it to a workforce component. Does not trigger playbook generation.
- [Link to Agent](https://docs.timbal.ai/api-reference/ace/link.md): Link an existing ACE to a workforce component.
- [Unlink from Agent](https://docs.timbal.ai/api-reference/ace/unlink.md): Detach the ACE linked to a workforce component.
- [List Policies](https://docs.timbal.ai/api-reference/ace/list-policies.md): List the policies declared on an ACE.
- [List Context Variables](https://docs.timbal.ai/api-reference/ace/list-context-vars.md): List the variables declared on an ACE.
- [Chat Completions](https://docs.timbal.ai/api-reference/ace/chat-completions.md): OpenAI-compatible chat completions endpoint for an ACE.
- [List Jobs](https://docs.timbal.ai/api-reference/ace/jobs/list.md): List jobs for an ACE, most recent first.
- [Enqueue Job](https://docs.timbal.ai/api-reference/ace/jobs/create.md): Enqueue a job against an ACE. Today: `regenerate` (playbook [re-]generation from the linked workforce's agent code file; the current playbook stays usable until the job commits a new one). The kind vocabulary grows server-side — future kinds include usage-driven adaptation.
- [Get Job](https://docs.timbal.ai/api-reference/ace/jobs/get.md): Get a single ACE job by id.
- [Cancel Job](https://docs.timbal.ai/api-reference/ace/jobs/cancel.md): Cancel an active ACE job.
- [Retry Job](https://docs.timbal.ai/api-reference/ace/jobs/retry.md): Retry a failed, cancelled, or errored ACE job.
- [List Alarms](https://docs.timbal.ai/api-reference/alarms/list.md): The metric alarms you can see in this org, with current state and channels.
- [Create Alarm](https://docs.timbal.ai/api-reference/alarms/create.md): Create a metric alarm with a threshold over evaluation periods.
- [Get Alarm](https://docs.timbal.ai/api-reference/alarms/get.md): One alarm's configuration, current state and linked channels.
- [Update Alarm](https://docs.timbal.ai/api-reference/alarms/update.md): Update alarm thresholds, evaluation settings, or enabled state.
- [Delete Alarm](https://docs.timbal.ai/api-reference/alarms/delete.md): Delete a metric alarm and its channel links.
- [Alarms Health](https://docs.timbal.ai/api-reference/alarms/health.md): For every enabled alarm, when the metric series behind it last produced a datapoint.
- [Alarm History](https://docs.timbal.ai/api-reference/alarms/history.md): State transition history for an alarm, newest first.
- [Attach Channel to Alarm](https://docs.timbal.ai/api-reference/alarms/attach-channel.md): Attach another notification channel to an alarm, so one condition reaches several destinations (page Slack and email the on-call, say).
- [Detach Channel from Alarm](https://docs.timbal.ai/api-reference/alarms/detach-channel.md): Detach a channel from an alarm. The `NotificationChannels` row itself is left alone — other alarms and notification rules may still be using it.
- [List Channels](https://docs.timbal.ai/api-reference/alarms/channels/list.md): List the organization's delivery channels — the addresses alarms can notify (email inboxes, Slack channels).
- [Create Channel](https://docs.timbal.ai/api-reference/alarms/channels/create.md): Create a delivery channel for this org, or reuse an existing one.
- [Delete Channel](https://docs.timbal.ai/api-reference/alarms/channels/delete.md): Delete a delivery channel for the organization.
- [Query Metric](https://docs.timbal.ai/api-reference/alarms/metrics/query.md): Time-bucketed count/sum/avg/min/max for one metric, with optional dimension filters.
- [Metrics Catalog](https://docs.timbal.ai/api-reference/alarms/metrics/catalog.md): Metric names and label values actually recorded for this org in the recent past. Use it to populate a metric picker: `GET /orgs/{org_id}/metrics` requires a name, and alarms reference names that only exist once something has emitted them.
- [List Metric Definitions](https://docs.timbal.ai/api-reference/alarms/metrics/definitions/list.md): The org's custom metric definitions and their current predicates.
- [Create Metric Definition](https://docs.timbal.ai/api-reference/alarms/metrics/definitions/create.md): Define a metric of your own, emitted as runs land. Once it exists it behaves like any platform metric: readable through `GET /orgs/{org_id}/metrics`, listed in the catalog with `origin: custom`, and alarmable with no extra setup.
- [Preview Metric Definition](https://docs.timbal.ai/api-reference/alarms/metrics/definitions/preview.md): Run a candidate predicate against recent stored traces without saving it, and see what it would have recorded.
- [Update Metric Definition](https://docs.timbal.ai/api-reference/alarms/metrics/definitions/update.md): Only the name and the enabled flag are mutable. The predicate and destination metric are fixed at creation: changing them would splice two different meanings into one series with nothing marking the seam, so a changed definition should be a new definition.
- [Delete Metric Definition](https://docs.timbal.ai/api-reference/alarms/metrics/definitions/delete.md): Stop emitting a custom metric. Takes effect within one flush interval (~10s).
- [List Connectors](https://docs.timbal.ai/api-reference/connectors/list.md): List connectors for the organization.
- [Get Connector](https://docs.timbal.ai/api-reference/connectors/get.md): Get a connector by id.
- [Update Connector](https://docs.timbal.ai/api-reference/connectors/update.md): Trigger a connector software update.
- [Push Local Config](https://docs.timbal.ai/api-reference/connectors/local-config.md): Push replacement connections/filesystems maps to a connector box.
- [Query Connector](https://docs.timbal.ai/api-reference/connectors/query.md): Run an ad-hoc SQL query against a connector's source and return the bounded result inline. Read-only by default (enforced node-side); write mode must also be allowed by the connection's local policy on the connector box. Requires a connector advertising query:sql (0.1.26+).
- [Rebind Connector](https://docs.timbal.ai/api-reference/connectors/rebind.md): Rebind a connector to a different knowledge base.
- [Revoke Connector](https://docs.timbal.ai/api-reference/connectors/revoke.md): Revoke a connector's credential and remove it from the fleet.
- [Copy Filesystem to Knowledge Base](https://docs.timbal.ai/api-reference/connectors/filesystems/copy.md): Copy a file or directory tree from a connector filesystem root into a knowledge base's document store. Store-only by default (parse: true to opt in). Requires fs:copy (0.1.27+).
- [Create Enrollment Token](https://docs.timbal.ai/api-reference/connectors/enrollment-tokens/create.md): Create a connector enrollment token.
- [List Connector Jobs](https://docs.timbal.ai/api-reference/connectors/jobs/list.md): List connector jobs for the organization.
- [Create Connector Job](https://docs.timbal.ai/api-reference/connectors/jobs/create.md): Dispatch a job to a connector.
- [Stop Connector Job](https://docs.timbal.ai/api-reference/connectors/jobs/stop.md): Cancel a running extract job. The row is terminalized as `stopped` first (so the run is dead even if the connector is offline or never acks), then a `StopJob` command aborts the connector-side task best-effort. Idempotent: stopping an already-terminal job returns its current state.
- [List Connector Syncs](https://docs.timbal.ai/api-reference/connectors/syncs/list.md): List connector syncs for the organization.
- [Create Connector Sync](https://docs.timbal.ai/api-reference/connectors/syncs/create.md): Create a connector sync configuration.
- [Get Connector Sync](https://docs.timbal.ai/api-reference/connectors/syncs/get.md): Get a connector sync by id.
- [Update Connector Sync](https://docs.timbal.ai/api-reference/connectors/syncs/update.md): Update a connector sync.
- [Delete Connector Sync](https://docs.timbal.ai/api-reference/connectors/syncs/delete.md): Delete a connector sync.
- [Run Sync Now](https://docs.timbal.ai/api-reference/connectors/syncs/run.md): Run a connector sync immediately.
- [Browse Connections](https://docs.timbal.ai/api-reference/connectors/browse/connections.md): List remote connections available to a connector.
- [Browse Tables](https://docs.timbal.ai/api-reference/connectors/browse/tables.md): List remote tables available to a connector.
- [Browse Table](https://docs.timbal.ai/api-reference/connectors/browse/table.md): Full introspection of one remote table: rich columns (defaults, identity, comments, precision), indexes, foreign keys, check constraints, table comment and size. Requires a connector advertising browse:describe (0.1.25+).
- [Browse Columns](https://docs.timbal.ai/api-reference/connectors/browse/columns.md): List columns for a remote table.
- [List Filesystems](https://docs.timbal.ai/api-reference/connectors/browse/filesystems/list.md): List filesystem roots configured on a connector (names only). Requires a connector advertising fs:browse (0.1.27+).
- [List Filesystem Entries](https://docs.timbal.ai/api-reference/connectors/browse/filesystems/entries.md): List one directory under a connector filesystem root, with size/mtime per entry, optional glob filter, sort, and bounded recursion (depth). Requires fs:browse (0.1.27+).
- [Search Filesystem](https://docs.timbal.ai/api-reference/connectors/browse/filesystems/search.md): Search file contents under a connector filesystem root with a line regex — bounded on files, matches, bytes, and time; binaries skipped. Runs entirely in-process on the node. Requires ConnectorsManage (reads file contents, same bar as ad-hoc SQL) and fs:browse (0.1.27+).
- [Summarize Filesystem](https://docs.timbal.ai/api-reference/connectors/browse/filesystems/summary.md): Summarize a directory tree on a connector filesystem root without listing it: file/dir counts, total bytes, largest files, extension histogram. The probe to run before a recursive copy. Requires fs:browse (0.1.27+).
- [Overview](https://docs.timbal.ai/models/overview.md): Specs, pricing, and capabilities for every supported model
- [Anthropic](https://docs.timbal.ai/models/anthropic.md): Claude Fable 5.1, Opus 5.5, Sonnet 5.5, and Haiku 5.5 models with specs, pricing, and capabilities
- [BytePlus](https://docs.timbal.ai/models/byteplus.md): Current Seed, DeepSeek, and GLM models, verified pricing, and retirement dates
- [Cerebras](https://docs.timbal.ai/models/cerebras.md): Wafer-scale inference at world-record token speeds with specs, pricing, and capabilities
- [Fireworks](https://docs.timbal.ai/models/fireworks.md): Open-source models via Fireworks serverless inference with specs, pricing, and capabilities
- [Google](https://docs.timbal.ai/models/google.md): Gemini API availability, verified Standard pricing, and migration guidance
- [Groq](https://docs.timbal.ai/models/groq.md): Ultra-low latency inference via Groq LPU with specs, pricing, and capabilities
- [Moonshot (Kimi)](https://docs.timbal.ai/models/moonshot.md): Kimi K3 and K2.x models via Moonshot's OpenAI-compatible API
- [OpenAI](https://docs.timbal.ai/models/openai.md): GPT-6, GPT-5, GPT-4, and o-series models with specs, pricing, and capabilities
- [SambaNova](https://docs.timbal.ai/models/sambanova.md): High-throughput inference on custom RDU hardware with specs, pricing, and capabilities
- [Timbal Auto](https://docs.timbal.ai/models/timbal.md): Let the platform pick the model for each turn
- [TogetherAI](https://docs.timbal.ai/models/togetherai.md): Open-source models via TogetherAI inference with specs, pricing, and capabilities
- [xAI](https://docs.timbal.ai/models/xai.md): Grok Build 0.1, Grok 4.7, Grok 4.6, Grok 4.5, and Grok 4.3 models with specs, pricing, and capabilities
- [Xiaomi MiMo](https://docs.timbal.ai/models/xiaomi.md): MiMo V2.5 models with specs, pricing, and capabilities
- [Overview](https://docs.timbal.ai/mcp-integration/index.md): Learn how to integrate Timbal with MCP on supported servers.
- [Claude](https://docs.timbal.ai/mcp-integration/claude.md): Learn how to connect Timbal to Claude in the browser with OAuth or in Claude Code with a Timbal API Key via MCP.
- [Cursor](https://docs.timbal.ai/mcp-integration/cursor.md): Learn how to connect Timbal to Cursor via MCP to access its features.
- [VS Code](https://docs.timbal.ai/mcp-integration/vscode.md): Learn how to connect Timbal to VS Code via MCP and use its functionality inside the editor.
- [Windsurf](https://docs.timbal.ai/mcp-integration/windsurf.md): Step-by-step instructions to integrate Timbal with Windsurf through MCP.
- [Zed](https://docs.timbal.ai/mcp-integration/zed.md): Connect Timbal to Zed via MCP

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.