> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Workforce

> Proxy HTTP requests to a deployed workforce component.

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).

<Note>
  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.
</Note>

## Supported HTTP methods

| Method              | Use case                                                        |
| ------------------- | --------------------------------------------------------------- |
| **GET**             | Read-only calls (e.g. health, metadata).                        |
| **POST**            | Typical RPC-style calls (e.g. `…/run`).                         |
| **PUT** / **PATCH** | Idempotent or partial updates when your component exposes them. |
| **DELETE**          | Deletes 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**.


## OpenAPI

````yaml POST /orgs/{org_id}/projects/{project_id}/workforce/{workforce}/{*path}
openapi: 3.1.0
info:
  title: Timbal Platform API
  description: Public API documentation for the Timbal platform
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.timbal.ai
    description: Production
  - url: https://api.dev.timbal.ai
    description: Development
security: []
tags:
  - name: ace
    description: Action Control Engine (ACE) operations
  - name: analytics
    description: Project analytics
  - name: billing
    description: Subscriptions, usage, and payment-related operations
  - name: content
    description: Re-sign stored content URLs
  - name: files
    description: File operations
  - name: iam
    description: IAM — actions, roles, users, and authorization introspection
  - name: k2
    description: Knowledge Bases v2 operations
  - name: orgs
    description: Organization operations
  - name: projects
    description: Project operations
  - name: runs
    description: Execution operations
  - name: templates
    description: Public project template catalog
  - name: users
    description: Authenticated user profile
paths:
  /orgs/{org_id}/projects/{project_id}/workforce/{workforce}/{*path}:
    post:
      tags:
        - projects
      description: Proxy HTTP requests to a deployed workforce component.
      operationId: workforce_proxy_post
      parameters:
        - name: org_id
          in: path
          description: Organization id
          required: true
          schema:
            type: string
        - name: project_id
          in: path
          description: Project id
          required: true
          schema:
            type: string
        - name: workforce
          in: path
          description: 'Workforce component: numeric id, manifest UUID, or name'
          required: true
          schema:
            type: string
        - name: path
          in: path
          description: Sub-path on the deployment server.
          required: true
          schema:
            type: string
        - name: rev
          in: query
          description: Git branch name (for example `main`).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response from the workforce deployment
        '404':
          description: No running deployment found for this component on this branch
        '502':
          description: Bad gateway
        '504':
          description: Gateway timeout
      security:
        - bearer_auth: []
components:
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: >-
        Timbal API key. Obtain your API key from the Timbal platform settings.
        See [Authentication](/api-reference/authentication) for more
        information.

````