# Timbal

## Docs

- [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
- [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
- [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
- [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 using built-in compaction strategies
- [Skills](https://docs.timbal.ai/agents/skills.md): Extend Agent capabilities through dynamic discovery of knowledge and tools
- [Structured Output](https://docs.timbal.ai/agents/structured-output.md): Use Pydantic models to structure and validate your agent outputs
- [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
- [Chat Completions](https://docs.timbal.ai/api-reference/ace/chat-completions.md): OpenAI-compatible **Chat Completions** endpoint scoped to an ACE. Accepts the native OpenAI `/v1/chat/completions` request body; set `stream: true` for an SSE response. The upstream provider is resolved from the `model` field: either explicit (`anthropic/claude-opus-4-7`, `google/gemini-2.5-pro`, …)…
- [Create from Agent](https://docs.timbal.ai/api-reference/ace/create-from-workforce.md): Create a new ACE attached to a workforce component and enqueue the initial generation job, seeded from the component's current source on the given branch. Returns `202` immediately with `{ace_uid, job_uid}`; poll `GET /ace/{ace_uid}/jobs/{job_uid}` for terminal state. The ACE's name defaults to `{pr…
- [Cancel Job](https://docs.timbal.ai/api-reference/ace/jobs/cancel.md): Cancel an active job. The job transitions to `status = 'cancelled'` once the cancellation takes effect. Returns `204` on accept; `409` if the job is not currently active.
- [Get Job](https://docs.timbal.ai/api-reference/ace/jobs/get.md): Fetch a single job. Poll this until `status` reaches a terminal value (`succeeded`, `failed`, `cancelled`, `error`).
- [List Jobs](https://docs.timbal.ai/api-reference/ace/jobs/list.md): List jobs for an ACE, most recent first.
- [Retry Job](https://docs.timbal.ai/api-reference/ace/jobs/retry.md): Re-enqueue a failed/cancelled/errored job with the same kind and input, returning a new `job_uid`. Returns `409` if the source job is still active or already succeeded, or if another job is active on this ACE.
- [Link to Agent](https://docs.timbal.ai/api-reference/ace/link.md): Link an existing ACE to a workforce component. Replaces any previously linked ACE.
- [List Context Variables](https://docs.timbal.ai/api-reference/ace/list-context-vars.md): List the variables declared on an ACE.
- [List Policies](https://docs.timbal.ai/api-reference/ace/list-policies.md): List the policies declared on an ACE.
- [Messages](https://docs.timbal.ai/api-reference/ace/messages.md): Anthropic-compatible **Messages** endpoint scoped to an ACE. Accepts the native Anthropic `/v1/messages` request body; set `stream: true` for an SSE response. The `model` field accepts either a bare model name (`claude-opus-4-7`) or an explicit `anthropic/<model>` prefix; any other provider prefix i…
- [Responses](https://docs.timbal.ai/api-reference/ace/responses.md): OpenAI-compatible **Responses API** endpoint scoped to an ACE. Accepts the native OpenAI `/v1/responses` request body; streaming responses are delivered as SSE. The upstream provider is resolved from the `model` field: either explicit (`google/gemini-2.5-pro`, `xai/grok-3`, …) or best-effort from th…
- [Unlink from Agent](https://docs.timbal.ai/api-reference/ace/unlink.md): Detach the ACE currently attached to a workforce component. The ACE itself is preserved and can be reattached to any workforce component. Active jobs on the ACE are NOT cancelled — use `POST /ace/{ace_uid}/jobs/{job_uid}/cancel` if that's what you want.
- [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
- [Upload file (temporary)](https://docs.timbal.ai/api-reference/files/upload.md): Upload a short-lived file (auto-deleted ~24h after upload).
- [Introduction](https://docs.timbal.ai/api-reference/introduction.md): Introduction to the Timbal Platform API
- [Create Backup](https://docs.timbal.ai/api-reference/knowledge-bases/backups/create.md): Create an on-demand backup of a knowledge base. While running, all read/write traffic on the KB returns 503 (Maintenance). A mutually-exclusive lock prevents concurrent backup/restore on the same KB (409 Conflict). `dry_run = true` skips the lock and the upload.
- [Get Backup](https://docs.timbal.ai/api-reference/knowledge-bases/backups/get.md): Get a single backup.
- [List Backups](https://docs.timbal.ai/api-reference/knowledge-bases/backups/list.md): List backups for a knowledge base.
- [Create Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/create.md): Create a new knowledge base
- [Delete Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/delete.md): Delete a knowledge base
- [Add File](https://docs.timbal.ai/api-reference/knowledge-bases/files/add.md): Add a file to a knowledge base via direct upload or remote URL fetch. Provide exactly one of `file` (raw bytes) or `url` (http/https; the server fetches it with an SSRF-hardened client).
- [Delete Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/delete.md): Delete a chunk. Requires `If-Match: <revision>` from the prior GET. The chunk disappears from listings immediately and stops affecting search after the next re-index pass.
- [Get Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/get.md): Get a single chunk by uid.
- [Insert Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/insert.md): Insert a new chunk. Place via `after_uid` / `before_uid` (mutually exclusive) or omit both to append.
- [List Chunks](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/list.md): List chunks for a knowledge base file, in document order. Layout metadata (`blocks`) is omitted from each item to keep responses small; fetch a single chunk by `uid` to retrieve it.
- [Update Chunk](https://docs.timbal.ai/api-reference/knowledge-bases/files/chunks/update.md): Edit a chunk's content / embed / page range. Requires `If-Match: <revision>` from the prior GET.
- [Create Directory](https://docs.timbal.ai/api-reference/knowledge-bases/files/create-dir.md): Create a virtual directory in the knowledge base
- [Delete File](https://docs.timbal.ai/api-reference/knowledge-bases/files/delete.md): Delete a file from a knowledge base
- [Get File](https://docs.timbal.ai/api-reference/knowledge-bases/files/get.md): Get a file with its parsings and embeddings metadata
- [List Files](https://docs.timbal.ai/api-reference/knowledge-bases/files/list.md): List files and folders in a knowledge base (use directory=/ for root)
- [Get Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/get.md): Get knowledge base details
- [List Knowledge Bases](https://docs.timbal.ai/api-reference/knowledge-bases/list.md): List knowledge bases in an organization
- [Create Policy Assignment](https://docs.timbal.ai/api-reference/knowledge-bases/policies/assignments/create.md): Bind an access-shaping rule to a role. Re-attaches if the binding was previously revoked.
- [Delete Policy Assignment](https://docs.timbal.ai/api-reference/knowledge-bases/policies/assignments/delete.md): Revoke a role binding (soft). Clears active access without deleting the row.
- [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.
- [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](https://docs.timbal.ai/api-reference/knowledge-bases/policies/create.md): Author a new 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. Requires `If-Match: <revision>` from the prior GET. Assignments remain for audit; the rule no longer applies.
- [Set Policy Enforcement](https://docs.timbal.ai/api-reference/knowledge-bases/policies/enforcement.md): Enable or disable enforcement of data-governance policies on K2 queries. Requires `k2.policies.manage`. When enabled, queries are rewritten to satisfy active policies or rejected if they cannot be safely constrained. Read the current value from `GET /orgs/{org_id}/k2/{kb_id}` (`governance_enforced`…
- [Get Policy](https://docs.timbal.ai/api-reference/knowledge-bases/policies/get.md): Fetch a single access-shaping rule by id.
- [List Policies](https://docs.timbal.ai/api-reference/knowledge-bases/policies/list.md): List access-shaping rules authored on a knowledge base.
- [Update Policy](https://docs.timbal.ai/api-reference/knowledge-bases/policies/update.md): Update an access-shaping rule. Requires `If-Match: <revision>` from the prior GET.
- [Query](https://docs.timbal.ai/api-reference/knowledge-bases/query.md): Execute a SQL query against the knowledge base
- [Restart Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/restart.md): Drop the knowledge base's in-memory connections so the next request opens a fresh database handle. Requires `k2.manage`.
- [Restore](https://docs.timbal.ai/api-reference/knowledge-bases/restores/create.md): Restore a knowledge base from a previously completed backup. While running, all read/write traffic on the KB returns 503 (Maintenance). A mutually-exclusive lock prevents concurrent backup/restore on the same KB (409 Conflict).
- [Get Restore](https://docs.timbal.ai/api-reference/knowledge-bases/restores/get.md): Get a single restore.
- [List Restores](https://docs.timbal.ai/api-reference/knowledge-bases/restores/list.md): List restore attempts for a knowledge base.
- [Get Schema](https://docs.timbal.ai/api-reference/knowledge-bases/schema.md): Get the schema for a knowledge base
- [Edit Knowledge Base](https://docs.timbal.ai/api-reference/knowledge-bases/update.md): Update a knowledge base.
- [Upload Data](https://docs.timbal.ai/api-reference/knowledge-bases/upload.md): Upload a data file into the knowledge base via direct upload or remote URL fetch
- [List Organizations](https://docs.timbal.ai/api-reference/me/list-orgs.md): List organizations the authenticated user belongs to
- [Create API Token](https://docs.timbal.ai/api-reference/me/tokens/create.md): Create an API credential for the authenticated user.
- [List API Tokens](https://docs.timbal.ai/api-reference/me/tokens/list.md): List the authenticated user's API credentials.
- [Revoke API Token](https://docs.timbal.ai/api-reference/me/tokens/revoke.md): Revoke an API credential owned by the authenticated user.
- [Update Profile](https://docs.timbal.ai/api-reference/me/update.md): Patch the authenticated user's profile. Omitted fields are left untouched; null clears nullable fields.
- [Get Credit Budgets](https://docs.timbal.ai/api-reference/orgs/billing/budgets/get.md): Read credit budgets for the organization. Filter with `project_id` or `role_id` to fetch a single target without listing the full org config.
- [Patch Credit Budgets](https://docs.timbal.ai/api-reference/orgs/billing/budgets/patch.md): Merge credit budget changes. Each row upserts when `limit_credits` is set, or removes the budget when `limit_credits` is null. Other configured targets are left unchanged.
- [Replace Credit Budgets](https://docs.timbal.ai/api-reference/orgs/billing/budgets/replace.md): Replace the organization's full credit budget configuration. Omitted targets are removed.
- [Update Overage Billing](https://docs.timbal.ai/api-reference/orgs/billing/overage.md): Enable or disable usage-based overage billing and set an optional credit cap for the organization.
- [List Account Contacts](https://docs.timbal.ai/api-reference/orgs/contacts/list.md): Account-side contacts assigned to an organization.
- [Create Organization](https://docs.timbal.ai/api-reference/orgs/create.md): Get in touch to create a new organization on Timbal
- [List Credit Grants](https://docs.timbal.ai/api-reference/orgs/credit-grants/list.md): Credit grants awarded to an organization, most recent first.
- [Create Domain](https://docs.timbal.ai/api-reference/orgs/domains/create.md): Add a custom domain to an organization
- [Delete Domain](https://docs.timbal.ai/api-reference/orgs/domains/delete.md): Delete a domain
- [Get Domain](https://docs.timbal.ai/api-reference/orgs/domains/get.md): Get a domain by ID. This endpoint triggers DNS validation and returns the live certificate status.
- [List Domains](https://docs.timbal.ai/api-reference/orgs/domains/list.md): List connected domains for an organization
- [List Embedding Models](https://docs.timbal.ai/api-reference/orgs/embedding-models/list.md): List all available embedding models for the organization
- [Get Organization](https://docs.timbal.ai/api-reference/orgs/get.md): Get an organization by ID
- [List IAM Actions](https://docs.timbal.ai/api-reference/orgs/iam/actions/list.md): Catalog of every action this organization may grant on a role. Org-scoped so future plans / feature flags can enable subsets per-org; today every org sees the full catalog. Use to drive the custom-role builder UI: render a checkbox per action, and a resource picker keyed on `resource.kind` for typed…
- [Check IAM Permissions](https://docs.timbal.ai/api-reference/orgs/iam/check.md): Forward authorization simulator. Evaluates one or more `(action, resource?)` checks against a user's effective grants and returns a decision per check, including the matched allow/deny grants that explain it. Mirrors the live evaluator exactly — same scope intersection, expiry filtering, and deny-be…
- [Get User Effective Grants](https://docs.timbal.ai/api-reference/orgs/iam/users/effective-grants.md): Dump the grants a user actually carries in this org, post-scope-intersection and expiry-filtered, with role attribution. Asking about yourself only requires membership; asking about another user requires `users.read`. Same effective grant contributed by N roles produces N rows.
- [Create channel](https://docs.timbal.ai/api-reference/orgs/notifications/create-channel.md): Create or reuse a notification channel for this org.
- [Create rule](https://docs.timbal.ai/api-reference/orgs/notifications/create-rule.md): Create an org-wide notification rule.
- [Delete channel](https://docs.timbal.ai/api-reference/orgs/notifications/delete-channel.md): Removes the channel for this org. Fails with 409 if rules reference it unless `force: true`.
- [Delete rule](https://docs.timbal.ai/api-reference/orgs/notifications/delete-rule.md): Deletes a rule with `project_id` unset only. **Org admin** only.
- [List channels](https://docs.timbal.ai/api-reference/orgs/notifications/list-channels.md): Returns all `NotificationChannels` rows for this organization (email and future types). Any org member may call.
- [List rules](https://docs.timbal.ai/api-reference/orgs/notifications/list-rules.md): List org-wide notification rules with their linked channels.
- [Create Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/create.md): Create a custom role for the organization.
- [Delete Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/delete.md): Delete a custom role. System roles cannot be deleted. Roles still attached to members return 409 with the assignee list — reassign first, then retry.
- [Get Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/get.md): Retrieve a role and the full set of grants it carries.
- [List Organization Roles](https://docs.timbal.ai/api-reference/orgs/roles/list.md): List roles available to an organization. Returns built-in system roles + any custom roles defined by the org.
- [Update Organization Role](https://docs.timbal.ai/api-reference/orgs/roles/update.md): Partially update a custom role. System roles are immutable.
- [Update Organization](https://docs.timbal.ai/api-reference/orgs/update.md): Partially update 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 a user from an organization
- [List Users](https://docs.timbal.ai/api-reference/orgs/users/list.md): List members of an organization. Requires `users.read`.
- [Update User Roles](https://docs.timbal.ai/api-reference/orgs/users/update.md): Replace a member's role attachments with the provided set. Each attachment is a `(role_id, scope?)` pair — the same role may appear multiple times scoped to different resources. Requires `users.edit`.
- [Pagination](https://docs.timbal.ai/api-reference/pagination.md): How to paginate through resources
- [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 and spend aggregates for a project.
- [List Sessions](https://docs.timbal.ai/api-reference/projects/composer/list.md): Retrieve all compose sessions for a project
- [List Plans](https://docs.timbal.ai/api-reference/projects/composer/plans-list.md): Plan markdown files from compose plan-mode sessions, newest first
- [Get Plan](https://docs.timbal.ai/api-reference/projects/composer/plans-single.md): Metadata and full markdown for one plan; `plan_id` is the `.md` filename without the extension
- [Prompt](https://docs.timbal.ai/api-reference/projects/composer/prompt.md): Send a prompt to the Timbal Composer agent
- [Get Session](https://docs.timbal.ai/api-reference/projects/composer/single.md): Fetch details for a specific compose session
- [Stop Session](https://docs.timbal.ai/api-reference/projects/composer/stop.md): Stop a running compose session
- [Create Project](https://docs.timbal.ai/api-reference/projects/create.md): Create a new project.
- [Delete Project](https://docs.timbal.ai/api-reference/projects/delete.md): Delete a project. Requires `projects.delete` on `projects:{project_id}`.
- [Create Environment](https://docs.timbal.ai/api-reference/projects/environments/create.md): Create a new environment and a matching git branch from the repo default branch. Requires `projects.envs.create` on `projects:{project_id}`.
- [Delete Environment](https://docs.timbal.ai/api-reference/projects/environments/delete.md): Delete an environment. Requires `projects.envs.delete` on `projects:{project_id}:envs:{env_id}`.
- [Deploy](https://docs.timbal.ai/api-reference/projects/environments/deploy.md): Deploy an environment (idempotent on the same rev). Requires `projects.envs.deploy` on `projects:{project_id}:envs:{env_id}`.
- [List Environment Deployments](https://docs.timbal.ai/api-reference/projects/environments/deployments/list.md): List deployments for an environment. Requires `projects.envs.read` on `projects:{project_id}`.
- [Get Metrics](https://docs.timbal.ai/api-reference/projects/environments/get-metrics.md): Query runtime metrics for an environment. Requires `projects.envs.metrics` on `projects:{project_id}:envs:{env_id}`.
- [List Environments](https://docs.timbal.ai/api-reference/projects/environments/list.md): List environments for a project. Requires `projects.envs.read` on `projects:{project_id}`.
- [Get Environment Logs](https://docs.timbal.ai/api-reference/projects/environments/logs.md): Fetch runtime logs for the active deployment of a specific component within an env. `component` selects the component kind (`ui` / `api` / `workforce`); when `component=workforce`, supply exactly one of `component_id` or `component_uid` to identify which one. `workforce` covers agent and workflow co…
- [Stop](https://docs.timbal.ai/api-reference/projects/environments/stop.md): Stop an environment. Destructive. Requires `projects.envs.stop` on `projects:{project_id}:envs:{env_id}`.
- [Update Branch](https://docs.timbal.ai/api-reference/projects/environments/update-branch.md): Set or clear the branch for an environment. Requires `projects.envs.branch` on `projects:{project_id}:envs:{env_id}`.
- [Update Config](https://docs.timbal.ai/api-reference/projects/environments/update-config.md): Update environment deploy config (CPU, memory, ephemeral storage, replica count). Requires `projects.envs.deploy_config` on `projects:{project_id}:envs:{env_id}`.
- [Update Domain](https://docs.timbal.ai/api-reference/projects/environments/update-domain.md): Attach, replace, or detach the custom domain mapped to an env. Set `domain_id` to assign or reassign; omit (or send null) to unassign. Requires `projects.envs.domain` on `projects:{project_id}:envs:{env_id}`.
- [Get Project](https://docs.timbal.ai/api-reference/projects/get.md): Get a project by ID. Requires `projects.read` on `projects:{project_id}`.
- [Link Knowledge Base](https://docs.timbal.ai/api-reference/projects/link-knowledge-base.md): Link a K2 knowledge base to a project. Replaces any previously linked KB.
- [List Projects](https://docs.timbal.ai/api-reference/projects/list.md): List projects in an organization, filtered to those the caller has `projects.read` on. Org admins (with `projects.read` on `projects:*`) see everything; scoped users see only the projects covered by their attachments.
- [Create rule](https://docs.timbal.ai/api-reference/projects/notifications/create-rule.md): Create a project-scoped notification rule.
- [Delete rule](https://docs.timbal.ai/api-reference/projects/notifications/delete-rule.md): Deletes a rule tied to this project. Requires `projects.notification_rules.manage` on `projects:{project_id}`.
- [List rules](https://docs.timbal.ai/api-reference/projects/notifications/list-rules.md): Returns rules scoped to a single **project** (e.g. deployment lifecycle emails). Each rule includes linked channels. Requires `projects.notification_rules.read` on `projects:{project_id}`.
- [Get Preview](https://docs.timbal.ai/api-reference/projects/previews/get.md): Get preview status (starting or running) and health when running
- [List Previews](https://docs.timbal.ai/api-reference/projects/previews/list.md): List project previews for the organization
- [Preview Logs](https://docs.timbal.ai/api-reference/projects/previews/logs.md): Tail the last N lines of a running preview component's dev server log (stdout+stderr merged). Admin only. Logs disappear when the preview exits.
- [Start Preview](https://docs.timbal.ai/api-reference/projects/previews/start.md): Start dev preview servers (API/UI) for a branch worktree; returns starting immediately, then ready after health checks
- [Stop Preview](https://docs.timbal.ai/api-reference/projects/previews/stop.md): Stop preview dev servers for a branch
- [Get Run](https://docs.timbal.ai/api-reference/projects/runs/get.md): Get a single run for a project (by run id or idempotency key). Returned when you initiated the run, or when you hold `projects.runs.list` for the project.
- [List Runs](https://docs.timbal.ai/api-reference/projects/runs/list.md): List runs for a project. Org members see their own runs; `projects.runs.list` is required to list all runs or filter by another user.
- [Add Reaction](https://docs.timbal.ai/api-reference/projects/runs/reactions-add.md): Add a reaction to a project run. Allowed when the caller initiated the run, or when the caller holds `projects.runs.react` for the project.
- [List Reactions](https://docs.timbal.ai/api-reference/projects/runs/reactions-list.md): List reactions for a project run. Returned when you initiated the run, or when you hold `projects.runs.list` for the project.
- [Unlink Knowledge Base](https://docs.timbal.ai/api-reference/projects/unlink-knowledge-base.md): Unlink the K2 knowledge base from a project.
- [Update Project](https://docs.timbal.ai/api-reference/projects/update.md): Edit project metadata. Requires `projects.edit` on `projects:{project_id}`.
- [Batch Create Variables](https://docs.timbal.ai/api-reference/projects/vars/batch-create.md): Batch create variables. Requires `projects.vars.manage` on `projects:{project_id}`.
- [Create Variable](https://docs.timbal.ai/api-reference/projects/vars/create.md): Create a new variable. Requires `projects.vars.manage` on `projects:{project_id}`.
- [Delete Variable](https://docs.timbal.ai/api-reference/projects/vars/delete.md): Delete a variable. Requires `projects.vars.manage` on `projects:{project_id}`.
- [Get Variable](https://docs.timbal.ai/api-reference/projects/vars/get.md): Get a variable by ID. Requires `projects.vars.read` on `projects:{project_id}`.
- [List Variables](https://docs.timbal.ai/api-reference/projects/vars/list.md): List variables for a project. Requires `projects.vars.read` on `projects:{project_id}`.
- [Update Variable](https://docs.timbal.ai/api-reference/projects/vars/update.md): Update a variable. Requires `projects.vars.manage` on `projects:{project_id}`.
- [Call Workforce](https://docs.timbal.ai/api-reference/projects/workforce/call.md): Proxy HTTP to a **running** workforce deployment (agent or workflow). Non-serverless: method and headers pass through; JSON on `/run` or `/stream` may get `context.platform_config` merged for SDK auth-back. Serverless: no upstream URL — the platform runs the workforce for this request. Pass `workfor…
- [Create Workforce](https://docs.timbal.ai/api-reference/projects/workforce/create.md): Create a workforce component (agent or workflow) on the git **branch** given by `rev`.
- [Delete Workforce](https://docs.timbal.ai/api-reference/projects/workforce/delete.md): Delete a workforce component on the git **branch** given by `rev`.
- [List Workforce](https://docs.timbal.ai/api-reference/projects/workforce/list.md): List workforce components on the git branch given by `rev`.
- [List Templates](https://docs.timbal.ai/api-reference/templates/list.md): Platform starter catalog for the CLI and create flows.
- [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
- [Events & Streaming](https://docs.timbal.ai/core-concepts/events.md): Monitor execution in real-time and handle streaming results
- [Runnables](https://docs.timbal.ai/core-concepts/runnables.md): Executable primitives that provide consistent interfaces for all Timbal components
- [Tracing & Observability](https://docs.timbal.ai/core-concepts/tracing.md): Comprehensive execution tracing with input/output/error/timing capture for complete observability
- [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/evals/index.md): Automated testing framework for Timbal agents and runnables
- [Running Evals](https://docs.timbal.ai/evals/running-evals.md): CLI usage, file discovery, and CI/CD integration
- [Comparison Validators](https://docs.timbal.ai/evals/validators/comparison.md): Validators for equality, containment, patterns, and numeric comparisons
- [Flow Validators](https://docs.timbal.ai/evals/validators/flow.md): Validators for checking execution sequences and parallel execution
- [Overview](https://docs.timbal.ai/evals/validators/index.md): Complete reference for all Timbal eval validators
- [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 semantic matching and language detection
- [Type Validators](https://docs.timbal.ai/evals/validators/type.md): Validators for type checking, JSON, email, and null validation
- [Writing Evals](https://docs.timbal.ai/evals/writing-evals.md): Learn how to write effective evals for your Timbal agents
- [Adaptive System Prompts](https://docs.timbal.ai/examples/agents/adaptive-system-prompts.md): Adapt agent behavior based on detected context or origin
- [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
- [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
- [Audio](https://docs.timbal.ai/examples/agents/audio.md): AI agents can process audio files for transcription and analysis using speech-to-text capabilities
- [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
- [CSV](https://docs.timbal.ai/examples/agents/csv.md): AI agents can analyze and process CSV data files for insights and data manipulation
- [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
- [Word](https://docs.timbal.ai/examples/agents/docx.md): AI agents can read and analyze Microsoft Word 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
- [Execution Behavior](https://docs.timbal.ai/examples/agents/execution-behavior.md): Validate agent execution flow, tool usage, and sequence of operations
- [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
- [Images](https://docs.timbal.ai/examples/agents/images.md): AI agents can analyze and understand images by processing visual content alongside text instructions
- [Input Parameters](https://docs.timbal.ai/examples/agents/input-validation.md): Pass input parameters to agents and validate the output response
- [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
- [Output Validation](https://docs.timbal.ai/examples/agents/output-validation.md): Validate agent responses using content checks, format validation, and semantic evaluation
- [PDF](https://docs.timbal.ai/examples/agents/pdf.md): AI agents can read and analyze PDF documents for content extraction and processing
- [Web Search](https://docs.timbal.ai/examples/agents/search.md): AI agents can search the web for real-time information using OpenAI or Anthropic models
- [Semantic Search with Embeddings](https://docs.timbal.ai/examples/agents/semantic-search.md): AI agents can create embeddings and perform intelligent semantic search through natural conversation
- [SQL Queries & Data Management](https://docs.timbal.ai/examples/agents/sql-queries.md): AI agents can add data to knowledge bases and then query it through natural conversation
- [Text-to-Speech](https://docs.timbal.ai/examples/agents/tts.md): AI agents can convert text to speech using OpenAI's TTS capabilities
- [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 WhatsApp assistant with webhooks, conversation persistence (Knowledge Base or JSONL), and support for text, audio, images, and documents
- [Overview](https://docs.timbal.ai/examples/index.md): Complete guides and building patterns for Timbal AI agents
- [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
- [Sequential Steps](https://docs.timbal.ai/examples/workflows/sequential-steps.md): Chain multiple processing steps with data passing between them
- [Workflow Composition](https://docs.timbal.ai/examples/workflows/workflow-composition.md): Nest workflows inside other workflows for modular pipelines
- [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
- [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
- [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
- [Observability](https://docs.timbal.ai/human-in-the-loop/observability.md): Status reasons, usage counters, and common patterns for paused runs
- [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
- [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
- [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
- [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.
- [Overview](https://docs.timbal.ai/mcp-integration/index.md): Learn how to integrate Timbal with MCP on supported servers.
- [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
- [Anthropic](https://docs.timbal.ai/models/anthropic.md): Claude 4 Opus, Sonnet, and Haiku models with specs, pricing, and capabilities
- [BytePlus](https://docs.timbal.ai/models/byteplus.md): Seed 2.0 and Seed 1.8 models with specs, pricing, and capabilities
- [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 3 and 2.5 series models with specs, pricing, and capabilities
- [Groq](https://docs.timbal.ai/models/groq.md): Ultra-low latency inference via Groq LPU with specs, pricing, and capabilities
- [OpenAI](https://docs.timbal.ai/models/openai.md): GPT-5, GPT-4, and o-series models with specs, pricing, and capabilities
- [Overview](https://docs.timbal.ai/models/overview.md): Specs, pricing, and capabilities for every supported model
- [SambaNova](https://docs.timbal.ai/models/sambanova.md): High-throughput inference on custom RDU hardware with specs, pricing, and capabilities
- [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 4 and Grok 4.1 models with specs, pricing, and capabilities
- [Xiaomi MiMo](https://docs.timbal.ai/models/xiaomi.md): MiMo V2 and V2.5 models with specs, pricing, and capabilities
- [Quickstart](https://docs.timbal.ai/quickstart.md): Build your first AI Agent with Timbal in a few lines of code
- [Agents & LLMs](https://docs.timbal.ai/workflows/agents-and-llms.md): Use Agents as workflow steps and build LLM routing pipelines
- [Branching](https://docs.timbal.ai/workflows/branching.md): Conditional step execution with the `when` parameter
- [Control Flow](https://docs.timbal.ai/workflows/control-flow.md): Manage step execution order with dependencies and data passing
- [Errors & Failure](https://docs.timbal.ai/workflows/errors-and-failure.md): How workflow steps fail, skip, and propagate errors
- [Human in the Loop](https://docs.timbal.ai/workflows/human-in-the-loop.md): Pause workflow steps for approval or user input, then resume
- [Overview](https://docs.timbal.ai/workflows/index.md): Build multi-step AI pipelines with explicit control flow

## OpenAPI Specs

- [openapi](https://docs.timbal.ai/api-reference/openapi.json)