format: md

Cowork / Dispatch (Environments Bridge)

Endpoints para gerenciar a bridge entre ambientes locais (Claude Code) e o servidor Anthropic, permitindo comunicação bidirecional via CCR (Code-Context-Reasoning).

---

format: md

POST /v1/environments/bridge

POST /v1/environments/bridge

Registra um environment local na bridge, estabelecendo a conexão inicial com o servidor.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
x-environment-runner-version	<version>	Sim
Anthropic-Worker-ID	<worker_id>	Sim
X-Trusted-Device-Token	<device_token>	Sim

Request Body

{
  "machine_name": "macbook-pro",
  "directory": "/home/user/project",
  "metadata": {"os": "macos"},
  "environment_id": "env_abc"
}

Response

{
  "environment_id": "env_abc"
}

Exemplo curl

curl -X POST http://localhost:4000/v1/environments/bridge \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "x-environment-runner-version: 1.0.0" \
  -H "Anthropic-Worker-ID: worker_abc" \
  -H "X-Trusted-Device-Token: token_abc" \
  -d '{
    "machine_name": "macbook-pro",
    "directory": "/home/user/project",
    "metadata": {"os": "macos"},
    "environment_id": "env_abc"
  }'

Códigos de Erro

Código	Significado
400	Body inválido ou headers faltando
401	Token ausente ou inválido
403	Proibido (sem permissão para bridge)
409	Environment já registrado
500	Erro interno

---

format: md

GET /v1/environments//work/poll

GET /v1/environments//work/poll

Polling para fila de trabalho do environment. Usado pelo cliente para buscar novas tarefas.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment registrado

Response

{
  "id": "work_abc",
  "data": {
    "type": "session",
    "id": "session_abc"
  }
}

Exemplo curl

curl -X GET "http://localhost:4000/v1/environments/env_abc/work/poll" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY"

Códigos de Erro

Código	Significado
401	Não autorizado
404	Environment não encontrado
500	Erro interno

---

format: md

POST /v1/environments/{env_id}/work/{work_id}/ack

POST /v1/environments/{env_id}/work/{work_id}/ack

Confirma o recebimento e início do processamento de um trabalho.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment
work_id	string	ID do trabalho

Request Body

{}

Exemplo curl

curl -X POST "http://localhost:4000/v1/environments/env_abc/work/work_abc/ack" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -d '{}'

Códigos de Erro

Código	Significado
401	Não autorizado
404	Environment ou trabalho não encontrado
409	Conflito (ack já processado)
500	Erro interno

---

format: md

POST /v1/environments//work//stop

POST /v1/environments//work//stop

Solicita a parada de um trabalho em execução no environment.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment
work_id	string	ID do trabalho a parar

Request Body

{
  "force": true
}

Exemplo curl

curl -X POST "http://localhost:4000/v1/environments/env_abc/work/work_abc/stop" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -d '{"force": true}'

Códigos de Erro

Código	Significado
401	Não autorizado
404	Environment ou trabalho não encontrado
500	Erro interno

---

format: md

DELETE /v1/environments/bridge/{environment_id}

DELETE /v1/environments/bridge/{environment_id}

Remove o registro de bridge de um environment, encerrando a conexão.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
environment_id	string	ID do environment a remover

Exemplo curl

curl -X DELETE "http://localhost:4000/v1/environments/bridge/env_abc" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY"

Códigos de Erro

Código	Significado
401	Não autorizado
404	Environment não encontrado
500	Erro interno

---

format: md

POST /v1/environments//bridge/reconnect

POST /v1/environments//bridge/reconnect

Reconecta um environment à bridge após desconexão temporária.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
x-environment-runner-version	<version>	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment

Request Body

{
  "session_id": "session_abc"
}

Exemplo curl

curl -X POST "http://localhost:4000/v1/environments/env_abc/bridge/reconnect" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "x-environment-runner-version: 1.0.0" \
  -d '{"session_id": "session_abc"}'

Códigos de Erro

Código	Significado
401	Não autorizado
404	Environment não encontrado
409	Sessão já ativa ou conflitante
500	Erro interno

---

format: md

GET /v1/environment_providers/private/organizations/{org_uuid}/environments

GET /v1/environment_providers/private/organizations/{org_uuid}/environments

Lista environments de uma organização.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
org_uuid	string	UUID da organização

Parâmetros Query

Parâmetro	Tipo	Descrição	Padrão
limit	integer	Número máximo de resultados	100
included_worker_types	string	Filtro por tipo de worker	cowork

Exemplo curl

curl -X GET "http://localhost:4000/v1/environment_providers/private/organizations/org_uuid_abc/environments?limit=100&included_worker_types=cowork" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY"

Códigos de Erro

Código	Significado
401	Não autorizado
404	Organização não encontrada
500	Erro interno

---

format: md

POST /v1/sessions (CCR)

POST /v1/sessions

Cria uma sessão CCR (Code-Context-Reasoning) vinculada a um environment bridge. Requer beta header ccr-byoc-2025-07-29.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	ccr-byoc-2025-07-29	Sim
anthropic-client-feature	ccr	Sim
x-organization-uuid	<org_uuid>	Sim
x-environment-runner-version	<version>	Sim

Request Body

{
  "title": "CCR Session",
  "events": [],
  "environment_id": "env_abc",
  "session_context": {
    "sources": []
  },
  "tags": ["dev"]
}

Response

{
  "id": "cse_abc"
}

Exemplo curl

curl -X POST http://localhost:4000/v1/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: ccr-byoc-2025-07-29" \
  -H "anthropic-client-feature: ccr" \
  -H "x-organization-uuid: org_abc" \
  -H "x-environment-runner-version: 1.0.0" \
  -d '{
    "title": "CCR Session",
    "events": [],
    "environment_id": "env_abc",
    "session_context": {"sources": []},
    "tags": ["dev"]
  }'

Códigos de Erro

Código	Significado
400	Body inválido
401	Não autorizado
403	Proibido (beta não habilitado)
404	Environment não encontrado
500	Erro interno

---

format: md

Bridge WebSocket Handshake

O handshake WebSocket da bridge segue um fluxo de 3 etapas para estabelecer comunicação full-duplex com o worker:

Etapa 1: Solicitar JWT de Worker

POST /v1/code/sessions/{id}/bridge

Obtém o token JWT e URL base para o worker se registrar.

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim

Response:

{
  "worker_jwt": "eyJhbGciOiJIUzI1NiIs...",
  "api_base_url": "https://worker-api.anthropic.com",
  "worker_epoch": 1720000000
}

Etapa 2: Registrar Worker

POST {api_base_url}/v1/code/sessions/{id}/worker/register

Registra o worker no serviço de backend.

Header	Valor	Obrigatório
Authorization	Bearer <ingress_token>	Sim

Response:

{
  "status": "registered"
}

Etapa 3: Conectar WebSocket

WebSocket: {api_base_url}`/v1/code/sessions/{id}``/worker/events/stream`

Header	Valor	Obrigatório
Authorization	Bearer <ingress_jwt>	Sim
Content-Type	application/json	Sim
anthropic-version	2023-06-01	Sim

Após conectado, o worker pode enviar e receber eventos JSON pelo WebSocket, incluindo heartbeats, tool calls, e updates de sessão.