Home
/
API
/
Agents

Agents

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 /derp-map

Responses

StatusMeaningDescriptionSchema
101Switching ProtocolsSwitching Protocols

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 /workspaceagents/aws-instance-identity

Body parameter

{
  "document": "string",
  "signature": "string"
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.AWSInstanceIdentityTokentrueInstance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.AuthenticateResponse

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 /workspaceagents/azure-instance-identity

Body parameter

{
  "encoding": "string",
  "signature": "string"
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.AzureInstanceIdentityTokentrueInstance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.AuthenticateResponse

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 /workspaceagents/google-instance-identity

Body parameter

{
  "json_web_token": "string"
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.GoogleInstanceIdentityTokentrueInstance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Submit workspace agent application health

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/app-health \
  -H 'Content-Type: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/me/app-health

Body parameter

{
  "healths": {
    "property1": "disabled",
    "property2": "disabled"
  }
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.PostAppHealthsRequesttrueApplication health request

Responses

StatusMeaningDescriptionSchema
200OKOK

To perform this operation, you must be authenticated. Learn more.

Coordinate workspace agent via Tailnet

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/coordinate \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/coordinate

It accepts a WebSocket connection to an agent that listens to incoming connections and publishes node updates.

Responses

StatusMeaningDescriptionSchema
101Switching ProtocolsSwitching Protocols

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 /workspaceagents/me/external-auth

Parameters

NameInTypeRequiredDescription
matchquerystringtrueMatch
idquerystringtrueProvider ID
listenquerybooleanfalseWait for a new token to be issued

Example responses

200 Response

{
  "access_token": "string",
  "password": "string",
  "token_extra": {},
  "type": "string",
  "url": "string",
  "username": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.ExternalAuthResponse

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 /workspaceagents/me/gitauth

Parameters

NameInTypeRequiredDescription
matchquerystringtrueMatch
idquerystringtrueProvider ID
listenquerybooleanfalseWait for a new token to be issued

Example responses

200 Response

{
  "access_token": "string",
  "password": "string",
  "token_extra": {},
  "type": "string",
  "url": "string",
  "username": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.ExternalAuthResponse

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 /workspaceagents/me/gitsshkey

Example responses

200 Response

{
  "private_key": "string",
  "public_key": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.GitSSHKey

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 /workspaceagents/me/logs

Body parameter

{
  "log_source_id": "string",
  "logs": [
    {
      "created_at": "string",
      "level": "trace",
      "output": "string"
    }
  ]
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.PatchLogstruelogs

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get authorized workspace agent manifest

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/manifest \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/manifest

Example responses

200 Response

{
  "agent_id": "string",
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_level": "owner",
      "slug": "string",
      "subdomain": true,
      "subdomain_name": "string",
      "url": "string"
    }
  ],
  "derp_force_websockets": true,
  "derpmap": {
    "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"
      }
    }
  },
  "directory": "string",
  "disable_direct_connections": true,
  "environment_variables": {
    "property1": "string",
    "property2": "string"
  },
  "git_auth_configs": 0,
  "metadata": [
    {
      "display_name": "string",
      "interval": 0,
      "key": "string",
      "script": "string",
      "timeout": 0
    }
  ],
  "motd_file": "string",
  "owner_name": "string",
  "scripts": [
    {
      "cron": "string",
      "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,
      "timeout": 0
    }
  ],
  "vscode_port_proxy_uri": "string",
  "workspace_id": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.Manifest

To perform this operation, you must be authenticated. Learn more.

Submit workspace agent stats

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/report-stats \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/me/report-stats

Body parameter

{
  "connection_count": 0,
  "connection_median_latency_ms": 0,
  "connections_by_proto": {
    "property1": 0,
    "property2": 0
  },
  "metrics": [
    {
      "labels": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "name": "string",
      "type": "counter",
      "value": 0
    }
  ],
  "rx_bytes": 0,
  "rx_packets": 0,
  "session_count_jetbrains": 0,
  "session_count_reconnecting_pty": 0,
  "session_count_ssh": 0,
  "session_count_vscode": 0,
  "tx_bytes": 0,
  "tx_packets": 0
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.StatstrueStats request

Example responses

200 Response

{
  "report_interval": 0
}

Responses

StatusMeaningDescriptionSchema
200OKOKagentsdk.StatsResponse

To perform this operation, you must be authenticated. Learn more.

Removed: Patch workspace agent logs

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/startup-logs \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /workspaceagents/me/startup-logs

Body parameter

{
  "log_source_id": "string",
  "logs": [
    {
      "created_at": "string",
      "level": "trace",
      "output": "string"
    }
  ]
}

Parameters

NameInTypeRequiredDescription
bodybodyagentsdk.PatchLogstruelogs

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.Response

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 /workspaceagents/{workspaceagent}

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace agent ID

Example responses

200 Response

{
  "api_version": "string",
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_level": "owner",
      "slug": "string",
      "subdomain": true,
      "subdomain_name": "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",
  "ready_at": "2019-08-24T14:15:22Z",
  "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  "scripts": [
    {
      "cron": "string",
      "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,
      "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

StatusMeaningDescriptionSchema
200OKOKcodersdk.WorkspaceAgent

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 /workspaceagents/{workspaceagent}/connection

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace 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
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.WorkspaceAgentConnectionInfo

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 /workspaceagents/{workspaceagent}/coordinate

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace agent ID

Responses

StatusMeaningDescriptionSchema
101Switching ProtocolsSwitching Protocols

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 /workspaceagents/{workspaceagent}/listening-ports

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace agent ID

Example responses

200 Response

{
  "ports": [
    {
      "network": "string",
      "port": 0,
      "process_name": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKOKcodersdk.WorkspaceAgentListeningPortsResponse

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 /workspaceagents/{workspaceagent}/logs

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace agent ID
beforequeryintegerfalseBefore log id
afterqueryintegerfalseAfter log id
followquerybooleanfalseFollow log stream
no_compressionquerybooleanfalseDisable 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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.WorkspaceAgentLog

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» created_atstring(date-time)false
» idintegerfalse
» levelcodersdk.LogLevelfalse
» outputstringfalse
» source_idstring(uuid)false

Enumerated Values

PropertyValue
leveltrace
leveldebug
levelinfo
levelwarn
levelerror

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 /workspaceagents/{workspaceagent}/pty

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace agent ID

Responses

StatusMeaningDescriptionSchema
101Switching ProtocolsSwitching Protocols

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 /workspaceagents/{workspaceagent}/startup-logs

Parameters

NameInTypeRequiredDescription
workspaceagentpathstring(uuid)trueWorkspace agent ID
beforequeryintegerfalseBefore log id
afterqueryintegerfalseAfter log id
followquerybooleanfalseFollow log stream
no_compressionquerybooleanfalseDisable 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

StatusMeaningDescriptionSchema
200OKOKarray of codersdk.WorkspaceAgentLog

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
[array item]arrayfalse
» created_atstring(date-time)false
» idintegerfalse
» levelcodersdk.LogLevelfalse
» outputstringfalse
» source_idstring(uuid)false

Enumerated Values

PropertyValue
leveltrace
leveldebug
levelinfo
levelwarn
levelerror

To perform this operation, you must be authenticated. Learn more.

See an opportunity to improve our docs? Make an edit.