# Agents
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 [#get-derp-map-updates]
### Code samples [#code-samples]
```sh
# 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 [#responses]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------------------ | ------------------- | ------ |
| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## User-scoped tailnet RPC connection [#user-scoped-tailnet-rpc-connection]
### Code samples [#code-samples-1]
```sh
# 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 [#responses-1]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------------------ | ------------------- | ------ |
| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Authenticate agent on AWS instance [#authenticate-agent-on-aws-instance]
### Code samples [#code-samples-2]
```sh
# 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
```json
{
"agent_name": "string",
"document": "string",
"signature": "string"
}
```
### Parameters [#parameters]
| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `body` | body | [agentsdk.AWSInstanceIdentityToken](/beta-docs/reference/api/schemas/#agentsdkawsinstanceidentitytoken) | true | Instance identity token. The optional agent\_name field disambiguates when multiple agents share the same instance ID. |
### Example responses [#example-responses]
> 200 Response
```json
{
"session_token": "string"
}
```
### Responses [#responses-2]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.AuthenticateResponse](/beta-docs/reference/api/schemas/#agentsdkauthenticateresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Authenticate agent on Azure instance [#authenticate-agent-on-azure-instance]
### Code samples [#code-samples-3]
```sh
# 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
```json
{
"agent_name": "string",
"encoding": "string",
"signature": "string"
}
```
### Parameters [#parameters-1]
| Name | In | Type | Required | Description |
| ------ | ---- | ----------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `body` | body | [agentsdk.AzureInstanceIdentityToken](/beta-docs/reference/api/schemas/#agentsdkazureinstanceidentitytoken) | true | Instance identity token. The optional agent\_name field disambiguates when multiple agents share the same instance ID. |
### Example responses [#example-responses-1]
> 200 Response
```json
{
"session_token": "string"
}
```
### Responses [#responses-3]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.AuthenticateResponse](/beta-docs/reference/api/schemas/#agentsdkauthenticateresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Authenticate agent on Google Cloud instance [#authenticate-agent-on-google-cloud-instance]
### Code samples [#code-samples-4]
```sh
# 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
```json
{
"agent_name": "string",
"json_web_token": "string"
}
```
### Parameters [#parameters-2]
| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `body` | body | [agentsdk.GoogleInstanceIdentityToken](/beta-docs/reference/api/schemas/#agentsdkgoogleinstanceidentitytoken) | true | Instance identity token. The optional agent\_name field disambiguates when multiple agents share the same instance ID. |
### Example responses [#example-responses-2]
> 200 Response
```json
{
"session_token": "string"
}
```
### Responses [#responses-4]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.AuthenticateResponse](/beta-docs/reference/api/schemas/#agentsdkauthenticateresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Patch workspace agent app status [#patch-workspace-agent-app-status]
### Code samples [#code-samples-5]
```sh
# 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
```json
{
"app_slug": "string",
"icon": "string",
"message": "string",
"needs_user_attention": true,
"state": "working",
"uri": "string"
}
```
### Parameters [#parameters-3]
| Name | In | Type | Required | Description |
| ------ | ---- | ----------------------------------------------------------------------------------- | -------- | ----------- |
| `body` | body | [agentsdk.PatchAppStatus](/beta-docs/reference/api/schemas/#agentsdkpatchappstatus) | true | app status |
### Example responses [#example-responses-3]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-5]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get workspace agent external auth [#get-workspace-agent-external-auth]
### Code samples [#code-samples-6]
```sh
# 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 [#parameters-4]
| Name | In | Type | Required | Description |
| -------- | ----- | ------- | -------- | --------------------------------- |
| `match` | query | string | true | Match |
| `id` | query | string | true | Provider ID |
| `listen` | query | boolean | false | Wait for a new token to be issued |
### Example responses [#example-responses-4]
> 200 Response
```json
{
"access_token": "string",
"expires_at": "string",
"password": "string",
"token_extra": {},
"type": "string",
"url": "string",
"username": "string"
}
```
### Responses [#responses-6]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.ExternalAuthResponse](/beta-docs/reference/api/schemas/#agentsdkexternalauthresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Removed: Get workspace agent git auth [#removed-get-workspace-agent-git-auth]
### Code samples [#code-samples-7]
```sh
# 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 [#parameters-5]
| Name | In | Type | Required | Description |
| -------- | ----- | ------- | -------- | --------------------------------- |
| `match` | query | string | true | Match |
| `id` | query | string | true | Provider ID |
| `listen` | query | boolean | false | Wait for a new token to be issued |
### Example responses [#example-responses-5]
> 200 Response
```json
{
"access_token": "string",
"expires_at": "string",
"password": "string",
"token_extra": {},
"type": "string",
"url": "string",
"username": "string"
}
```
### Responses [#responses-7]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.ExternalAuthResponse](/beta-docs/reference/api/schemas/#agentsdkexternalauthresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get workspace agent Git SSH key [#get-workspace-agent-git-ssh-key]
### Code samples [#code-samples-8]
```sh
# 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 [#example-responses-6]
> 200 Response
```json
{
"private_key": "string",
"public_key": "string"
}
```
### Responses [#responses-8]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.GitSSHKey](/beta-docs/reference/api/schemas/#agentsdkgitsshkey) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Post workspace agent log source [#post-workspace-agent-log-source]
### Code samples [#code-samples-9]
```sh
# 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
```json
{
"display_name": "string",
"icon": "string",
"id": "string"
}
```
### Parameters [#parameters-6]
| Name | In | Type | Required | Description |
| ------ | ---- | ----------------------------------------------------------------------------------------------- | -------- | ------------------ |
| `body` | body | [agentsdk.PostLogSourceRequest](/beta-docs/reference/api/schemas/#agentsdkpostlogsourcerequest) | true | Log source request |
### Example responses [#example-responses-7]
> 200 Response
```json
{
"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 [#responses-9]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceAgentLogSource](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlogsource) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Patch workspace agent logs [#patch-workspace-agent-logs]
### Code samples [#code-samples-10]
```sh
# 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
```json
{
"log_source_id": "string",
"logs": [
{
"created_at": "string",
"level": "trace",
"output": "string"
}
]
}
```
### Parameters [#parameters-7]
| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------------------------------------- | -------- | ----------- |
| `body` | body | [agentsdk.PatchLogs](/beta-docs/reference/api/schemas/#agentsdkpatchlogs) | true | logs |
### Example responses [#example-responses-8]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-10]
| Status | Meaning | Description | Schema |
| ------ | ----------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
| 413 | [Payload Too Large](https://tools.ietf.org/html/rfc7231#section-6.5.11) | Agent log storage limit exceeded | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get workspace agent reinitialization [#get-workspace-agent-reinitialization]
### Code samples [#code-samples-11]
```sh
# 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 [#parameters-8]
| Name | In | Type | Required | Description |
| ------ | ----- | ------- | -------- | ------------------------------- |
| `wait` | query | boolean | false | Opt in to durable reinit checks |
### Example responses [#example-responses-9]
> 200 Response
```json
{
"owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
"reason": "prebuild_claimed",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}
```
### Responses [#responses-11]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.ReinitializationEvent](/beta-docs/reference/api/schemas/#agentsdkreinitializationevent) |
| 409 | [Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8) | Conflict | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get workspace agent by ID [#get-workspace-agent-by-id]
### Code samples [#code-samples-12]
```sh
# 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 [#parameters-9]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
### Example responses [#example-responses-10]
> 200 Response
```json
{
"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,
"metadata": [
{
"description": {
"display_name": "string",
"interval": 0,
"key": "string",
"script": "string",
"timeout": 0
},
"result": {
"age": 0,
"collected_at": "2019-08-24T14:15:22Z",
"error": "string",
"value": "string"
}
}
],
"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 [#responses-12]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceAgent](/beta-docs/reference/api/schemas/#codersdkworkspaceagent) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get connection info for workspace agent [#get-connection-info-for-workspace-agent]
### Code samples [#code-samples-13]
```sh
# 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 [#parameters-10]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
### Example responses [#example-responses-11]
> 200 Response
```json
{
"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 [#responses-13]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [workspacesdk.AgentConnectionInfo](/beta-docs/reference/api/schemas/#workspacesdkagentconnectioninfo) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get running containers for workspace agent [#get-running-containers-for-workspace-agent]
### Code samples [#code-samples-14]
```sh
# 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 [#parameters-11]
| Name | In | Type | Required | Description |
| ---------------- | ----- | ----------------- | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
| `label` | query | string(key=value) | true | Labels |
### Example responses [#example-responses-12]
> 200 Response
```json
{
"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 [#responses-14]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceAgentListContainersResponse](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlistcontainersresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Delete devcontainer for workspace agent [#delete-devcontainer-for-workspace-agent]
### Code samples [#code-samples-15]
```sh
# 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 [#parameters-12]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
| `devcontainer` | path | string | true | Devcontainer ID |
### Responses [#responses-15]
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Recreate devcontainer for workspace agent [#recreate-devcontainer-for-workspace-agent]
### Code samples [#code-samples-16]
```sh
# 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 [#parameters-13]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
| `devcontainer` | path | string | true | Devcontainer ID |
### Example responses [#example-responses-13]
> 202 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-16]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 202 | [Accepted](https://tools.ietf.org/html/rfc7231#section-6.3.3) | Accepted | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Watch workspace agent for container updates [#watch-workspace-agent-for-container-updates]
### Code samples [#code-samples-17]
```sh
# 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 [#parameters-14]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
### Example responses [#example-responses-14]
> 200 Response
```json
{
"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 [#responses-17]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceAgentListContainersResponse](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlistcontainersresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Coordinate workspace agent [#coordinate-workspace-agent]
### Code samples [#code-samples-18]
```sh
# 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 [#parameters-15]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
### Responses [#responses-18]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------------------ | ------------------- | ------ |
| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get listening ports for workspace agent [#get-listening-ports-for-workspace-agent]
### Code samples [#code-samples-19]
```sh
# 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 [#parameters-16]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
### Example responses [#example-responses-15]
> 200 Response
```json
{
"ports": [
{
"network": "string",
"port": 0,
"process_name": "string"
}
]
}
```
### Responses [#responses-19]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceAgentListeningPortsResponse](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlisteningportsresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get logs by workspace agent [#get-logs-by-workspace-agent]
### Code samples [#code-samples-20]
```sh
# 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 [#parameters-17]
| Name | In | Type | Required | Description |
| ---------------- | ----- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
| `before` | query | integer | false | Before log id |
| `after` | query | integer | false | After log id |
| `follow` | query | boolean | false | Follow log stream |
| `no_compression` | query | boolean | false | Disable compression for WebSocket connection |
| `format` | query | string | false | Log output format. Accepted: 'json' (default), 'text' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true. |
#### Enumerated Values [#enumerated-values]
| Parameter | Value(s) |
| --------- | -------------- |
| `format` | `json`, `text` |
### Example responses [#example-responses-16]
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": 0,
"level": "trace",
"output": "string",
"source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81"
}
]
```
### Responses [#responses-20]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.WorkspaceAgentLog](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlog) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ----------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | false | | |
| `» id` | integer | false | | |
| `» level` | [codersdk.LogLevel](/beta-docs/reference/api/schemas/#codersdkloglevel) | false | | |
| `» output` | string | false | | |
| `» source_id` | string(uuid) | false | | |
#### Enumerated Values [#enumerated-values-1]
| Property | Value(s) |
| -------- | ----------------------------------------- |
| `level` | `debug`, `error`, `info`, `trace`, `warn` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Open PTY to workspace agent [#open-pty-to-workspace-agent]
### Code samples [#code-samples-21]
```sh
# 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 [#parameters-18]
| Name | In | Type | Required | Description |
| ---------------- | ---- | ------------ | -------- | ------------------ |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
### Responses [#responses-21]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------------------ | ------------------- | ------ |
| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Removed: Get logs by workspace agent [#removed-get-logs-by-workspace-agent]
### Code samples [#code-samples-22]
```sh
# 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 [#parameters-19]
| Name | In | Type | Required | Description |
| ---------------- | ----- | ------------ | -------- | -------------------------------------------- |
| `workspaceagent` | path | string(uuid) | true | Workspace agent ID |
| `before` | query | integer | false | Before log id |
| `after` | query | integer | false | After log id |
| `follow` | query | boolean | false | Follow log stream |
| `no_compression` | query | boolean | false | Disable compression for WebSocket connection |
### Example responses [#example-responses-17]
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": 0,
"level": "trace",
"output": "string",
"source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81"
}
]
```
### Responses [#responses-22]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.WorkspaceAgentLog](/beta-docs/reference/api/schemas/#codersdkworkspaceagentlog) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ----------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | false | | |
| `» id` | integer | false | | |
| `» level` | [codersdk.LogLevel](/beta-docs/reference/api/schemas/#codersdkloglevel) | false | | |
| `» output` | string | false | | |
| `» source_id` | string(uuid) | false | | |
#### Enumerated Values [#enumerated-values-2]
| Property | Value(s) |
| -------- | ----------------------------------------- |
| `level` | `debug`, `error`, `info`, `trace`, `warn` |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).