Skip to main content
POST
/
orgs
/
{org_id}
/
projects
/
{project_id}
/
workforce
/
{workforce}
/
{*path}
cURL
curl --request POST \
  --url https://api.timbal.ai/orgs/{org_id}/projects/{project_id}/workforce/{workforce}/{*path} \
  --header 'Authorization: Bearer <token>'
This route is a gateway proxy to a running workforce deployment (an agent or workflow). The platform forwards your HTTP request to the deployment; responses pass back through unchanged (aside from normal proxy behavior).
The reference below is for POST so the API playground and generated fields render. The same path and parameters apply to GET, PUT, PATCH, and DELETE — use the verb you need when calling the API directly.

​
Supported HTTP methods

MethodUse case
GETRead-only calls (e.g. health, metadata).
POSTTypical RPC-style calls (e.g. …/run).
PUT / PATCHIdempotent or partial updates when your component exposes them.
DELETEDeletes or teardown actions your component exposes.
Path, query, and auth are the same for every method. The deployment must handle the method you send.

​
Path and query

  • workforce — Which component to hit: numeric id, manifest UUID, or name (same identifiers you use elsewhere in the project API).
  • path — Suffix on the deployment server after the component segment (for example run or healthcheck). Use the path your running app defines; can be empty for the deployment root.
  • rev (query, required) — Git branch the deployment is tied to (for example main).

​
Limits

  • WebSocket upgrades are not supported on this proxy route.
  • If nothing is running for that component on rev, you get 404. If the deployment returns an error upstream, you may see 502.

Authorizations

​
Authorization
string
header
required

Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.

Path Parameters

​
org_id
string
required

Organization id

​
project_id
string
required

Project id

​
workforce
string
required

Workforce component: numeric id, manifest UUID, or name

​
path
string
required

Path on the deployment server after the component segment (for example run or healthcheck). Leave empty to call the deployment root.

Query Parameters

​
rev
string
required

Git branch name (for example main).

Response

Response from the workforce deployment