Workspace agent endpoints. These power the workspace agent daemon defined by the coder_agent Terraform resource. This API is NOT the Coder Agents Chats API. For programmatic access to AI Coder Agents, see the Chats API.
Get DERP map updates
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/derp-map \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/derp-map
Responses
To perform this operation, you must be authenticated. Learn more .
User-scoped tailnet RPC connection
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/tailnet \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/tailnet
Responses
To perform this operation, you must be authenticated. Learn more .
Authenticate agent on AWS instance
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/aws-instance-identity \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/workspaceagents/aws-instance-identity
Body parameter
{
"agent_name": "string",
"document": "string",
"signature": "string"
}
Parameters
Name In Type Required Description bodybody agentsdk.AWSInstanceIdentityToken true Instance identity token. The optional agent_name field disambiguates when multiple agents share the same instance ID.
Example responses
200 Response
{
"session_token": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Authenticate agent on Azure instance
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/azure-instance-identity \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/workspaceagents/azure-instance-identity
Body parameter
{
"agent_name": "string",
"encoding": "string",
"signature": "string"
}
Parameters
Name In Type Required Description bodybody agentsdk.AzureInstanceIdentityToken true Instance identity token. The optional agent_name field disambiguates when multiple agents share the same instance ID.
Example responses
200 Response
{
"session_token": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Authenticate agent on Google Cloud instance
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/google-instance-identity \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/workspaceagents/google-instance-identity
Body parameter
{
"agent_name": "string",
"json_web_token": "string"
}
Parameters
Name In Type Required Description bodybody agentsdk.GoogleInstanceIdentityToken true Instance identity token. The optional agent_name field disambiguates when multiple agents share the same instance ID.
Example responses
200 Response
{
"session_token": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Patch workspace agent app status
Code samples
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/app-status \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
PATCH /api/v2/workspaceagents/me/app-status
Body parameter
{
"app_slug": "string",
"icon": "string",
"message": "string",
"needs_user_attention": true,
"state": "working",
"uri": "string"
}
Parameters
Example responses
200 Response
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get workspace agent external auth
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/external-auth?match=string&id=string \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/me/external-auth
Parameters
Name In Type Required Description matchquery string true Match idquery string true Provider ID listenquery boolean false Wait for a new token to be issued
Example responses
200 Response
{
"access_token": "string",
"expires_at": "string",
"password": "string",
"token_extra": {},
"type": "string",
"url": "string",
"username": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Removed: Get workspace agent git auth
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitauth?match=string&id=string \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/me/gitauth
Parameters
Name In Type Required Description matchquery string true Match idquery string true Provider ID listenquery boolean false Wait for a new token to be issued
Example responses
200 Response
{
"access_token": "string",
"expires_at": "string",
"password": "string",
"token_extra": {},
"type": "string",
"url": "string",
"username": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get workspace agent Git SSH key
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitsshkey \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/me/gitsshkey
Example responses
200 Response
{
"private_key": "string",
"public_key": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Post workspace agent log source
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/log-source \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/workspaceagents/me/log-source
Body parameter
{
"display_name": "string",
"icon": "string",
"id": "string"
}
Parameters
Example responses
200 Response
{
"created_at": "2019-08-24T14:15:22Z",
"display_name": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"workspace_agent_id": "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Patch workspace agent logs
Code samples
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/logs \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
PATCH /api/v2/workspaceagents/me/logs
Body parameter
{
"log_source_id": "string",
"logs": [
{
"created_at": "string",
"level": "trace",
"output": "string"
}
]
}
Parameters
Example responses
200 Response
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get workspace agent reinitialization
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/reinit \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/me/reinit
Parameters
Name In Type Required Description waitquery boolean false Opt in to durable reinit checks
Example responses
200 Response
{
"owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
"reason": "prebuild_claimed",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get workspace agent by ID
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID
Example responses
200 Response
{
"api_version": "string",
"apps": [
{
"command": "string",
"display_name": "string",
"external": true,
"group": "string",
"health": "disabled",
"healthcheck": {
"interval": 0,
"threshold": 0,
"url": "string"
},
"hidden": true,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"open_in": "slim-window",
"sharing_level": "owner",
"slug": "string",
"statuses": [
{
"agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
"app_id": "affd1d10-9538-4fc8-9e0b-4594a28c1335",
"created_at": "2019-08-24T14:15:22Z",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"message": "string",
"needs_user_attention": true,
"state": "working",
"uri": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
],
"subdomain": true,
"subdomain_name": "string",
"tooltip": "string",
"url": "string"
}
],
"architecture": "string",
"connection_timeout_seconds": 0,
"created_at": "2019-08-24T14:15:22Z",
"directory": "string",
"disconnected_at": "2019-08-24T14:15:22Z",
"display_apps": [
"vscode"
],
"environment_variables": {
"property1": "string",
"property2": "string"
},
"expanded_directory": "string",
"first_connected_at": "2019-08-24T14:15:22Z",
"health": {
"healthy": false,
"reason": "agent has lost connection"
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"instance_id": "string",
"last_connected_at": "2019-08-24T14:15:22Z",
"latency": {
"property1": {
"latency_ms": 0,
"preferred": true
},
"property2": {
"latency_ms": 0,
"preferred": true
}
},
"lifecycle_state": "created",
"log_sources": [
{
"created_at": "2019-08-24T14:15:22Z",
"display_name": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"workspace_agent_id": "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}
],
"logs_length": 0,
"logs_overflowed": true,
"name": "string",
"operating_system": "string",
"parent_id": {
"uuid": "string",
"valid": true
},
"ready_at": "2019-08-24T14:15:22Z",
"resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
"scripts": [
{
"cron": "string",
"display_name": "string",
"exit_code": 0,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"log_path": "string",
"log_source_id": "4197ab25-95cf-4b91-9c78-f7f2af5d353a",
"run_on_start": true,
"run_on_stop": true,
"script": "string",
"start_blocks_login": true,
"status": "ok",
"timeout": 0
}
],
"started_at": "2019-08-24T14:15:22Z",
"startup_script_behavior": "blocking",
"status": "connecting",
"subsystems": [
"envbox"
],
"troubleshooting_url": "string",
"updated_at": "2019-08-24T14:15:22Z",
"version": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get connection info for workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/connection \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/connection
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID
Example responses
200 Response
{
"derp_force_websockets": true,
"derp_map": {
"homeParams": {
"regionScore": {
"property1": 0,
"property2": 0
}
},
"omitDefaultRegions": true,
"regions": {
"property1": {
"avoid": true,
"embeddedRelay": true,
"nodes": [
{
"canPort80": true,
"certName": "string",
"derpport": 0,
"forceHTTP": true,
"hostName": "string",
"insecureForTests": true,
"ipv4": "string",
"ipv6": "string",
"name": "string",
"regionID": 0,
"stunonly": true,
"stunport": 0,
"stuntestIP": "string"
}
],
"regionCode": "string",
"regionID": 0,
"regionName": "string"
},
"property2": {
"avoid": true,
"embeddedRelay": true,
"nodes": [
{
"canPort80": true,
"certName": "string",
"derpport": 0,
"forceHTTP": true,
"hostName": "string",
"insecureForTests": true,
"ipv4": "string",
"ipv6": "string",
"name": "string",
"regionID": 0,
"stunonly": true,
"stunport": 0,
"stuntestIP": "string"
}
],
"regionCode": "string",
"regionID": 0,
"regionName": "string"
}
}
},
"disable_direct_connections": true,
"hostname_suffix": "string"
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get running containers for workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers?label=string \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/containers
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID labelquery string(key=value) true Labels
Example responses
200 Response
{
"containers": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"image": "string",
"labels": {
"property1": "string",
"property2": "string"
},
"name": "string",
"ports": [
{
"host_ip": "string",
"host_port": 0,
"network": "string",
"port": 0
}
],
"running": true,
"status": "string",
"volumes": {
"property1": "string",
"property2": "string"
}
}
],
"devcontainers": [
{
"agent": {
"directory": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"config_path": "string",
"container": {
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"image": "string",
"labels": {
"property1": "string",
"property2": "string"
},
"name": "string",
"ports": [
{
"host_ip": "string",
"host_port": 0,
"network": "string",
"port": 0
}
],
"running": true,
"status": "string",
"volumes": {
"property1": "string",
"property2": "string"
}
},
"dirty": true,
"error": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"status": "running",
"subagent_id": {
"uuid": "string",
"valid": true
},
"workspace_folder": "string"
}
],
"warnings": [
"string"
]
}
Responses
To perform this operation, you must be authenticated. Learn more .
Delete devcontainer for workspace agent
Code samples
# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer} \
-H 'Coder-Session-Token: API_KEY'
DELETE /api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID devcontainerpath string true Devcontainer ID
Responses
Status Meaning Description Schema 204 No Content No Content
To perform this operation, you must be authenticated. Learn more .
Recreate devcontainer for workspace agent
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}/recreate \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}/recreate
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID devcontainerpath string true Devcontainer ID
Example responses
202 Response
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
Responses
To perform this operation, you must be authenticated. Learn more .
Watch workspace agent for container updates
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/watch \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/containers/watch
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID
Example responses
200 Response
{
"containers": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"image": "string",
"labels": {
"property1": "string",
"property2": "string"
},
"name": "string",
"ports": [
{
"host_ip": "string",
"host_port": 0,
"network": "string",
"port": 0
}
],
"running": true,
"status": "string",
"volumes": {
"property1": "string",
"property2": "string"
}
}
],
"devcontainers": [
{
"agent": {
"directory": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
},
"config_path": "string",
"container": {
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"image": "string",
"labels": {
"property1": "string",
"property2": "string"
},
"name": "string",
"ports": [
{
"host_ip": "string",
"host_port": 0,
"network": "string",
"port": 0
}
],
"running": true,
"status": "string",
"volumes": {
"property1": "string",
"property2": "string"
}
},
"dirty": true,
"error": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"status": "running",
"subagent_id": {
"uuid": "string",
"valid": true
},
"workspace_folder": "string"
}
],
"warnings": [
"string"
]
}
Responses
To perform this operation, you must be authenticated. Learn more .
Coordinate workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/coordinate \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/coordinate
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID
Responses
To perform this operation, you must be authenticated. Learn more .
Get listening ports for workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/listening-ports \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/listening-ports
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID
Example responses
200 Response
{
"ports": [
{
"network": "string",
"port": 0,
"process_name": "string"
}
]
}
Responses
To perform this operation, you must be authenticated. Learn more .
Get logs by workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/logs \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/logs
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID beforequery integer false Before log id afterquery integer false After log id followquery boolean false Follow log stream no_compressionquery boolean false Disable compression for WebSocket connection formatquery string false Log output format. Accepted: 'json' (default), 'text' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true.
Enumerated Values
Parameter Value(s) formatjson, text
Example responses
200 Response
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": 0,
"level": "trace",
"output": "string",
"source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81"
}
]
Responses
Response Schema
Status Code 200
Name Type Required Restrictions Description [array item]array false » created_atstring(date-time) false » idinteger false » levelcodersdk.LogLevel false » outputstring false » source_idstring(uuid) false
Enumerated Values
Property Value(s) leveldebug, error, info, trace, warn
To perform this operation, you must be authenticated. Learn more .
Open PTY to workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/pty \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/pty
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID
Responses
To perform this operation, you must be authenticated. Learn more .
Removed: Get logs by workspace agent
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/startup-logs \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/workspaceagents/{workspaceagent}/startup-logs
Parameters
Name In Type Required Description workspaceagentpath string(uuid) true Workspace agent ID beforequery integer false Before log id afterquery integer false After log id followquery boolean false Follow log stream no_compressionquery boolean false Disable compression for WebSocket connection
Example responses
200 Response
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": 0,
"level": "trace",
"output": "string",
"source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81"
}
]
Responses
Response Schema
Status Code 200
Name Type Required Restrictions Description [array item]array false » created_atstring(date-time) false » idinteger false » levelcodersdk.LogLevel false » outputstring false » source_idstring(uuid) false
Enumerated Values
Property Value(s) leveldebug, error, info, trace, warn
To perform this operation, you must be authenticated. Learn more .