Public API

Alpha

To help you integrate Coder into your automated workflows, we've documented our API.

Documentation

Please note that the API is under active development; expect breaking changes as we finalize the endpoints.

Authentication

Use of the API requires authentication with a session token. You can generate one using the Coder CLI:

If you haven't already, authenticate your CLI with your workspace.
Run coder tokens create <TOKEN_NAME>

Save the token that's returned to use in your HTTP headers:

curl \
-X GET "https://apidocs.coder.com/api/" \
-H "accept: application/json" \
-H "Session-Token: Bk...nt"

Examples

These are example Coder API calls for common tasks. Note that the site-manager role is required to be perform specific actions and without it, API results will be limited to a user's member role.

Assign your Access URL, Session-Token and other resources like images and workspaces to variables for easier substitution in the curl commands.

export ACCESS_URL "https://coder.acme.com"
export API_KEY="MUdzI3UMvF-Qlwovt-----0CL0kTbADQl"
export API_ROUTE="api/v0"
export IMAGE_ID="622b3f6e-dd6fd08-----ba38c73c9639"

Example: get active SSH users in 1 week increments in August

For a full list of categories and filters, see Usage metrics.

# Currently in the private API
API_ROUTE=api/private curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/metrics/activity?\
start=2022-08-01T00:00:00.000000Z&end=2022-08-31T00:00:00.000000Z\
&category=tunnel\
&interval=1 week" \
--header "Session-Token: $API_KEY"

Example: get audit logs for a workspace and resource type

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/audit?\
limit=10\
&resource_id=$WS_ID_PHP\
&resource_type=environment" \
  --header "Session-Token: $API_KEY"

Example: get audit logs for workspace created in a Unix seconds period

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/audit?\
range_start=1646092800\
&range_end=1646697600\
&resource_type=environment\
&action=create" \
--header "Session-Token: $API_KEY"

Example: generate a session token for a user

curl --request POST \
  --url $ACCESS_URL/$API_ROUTE/api-keys/613e75c4-faef2f87-----376e1f229b6 \
  --header "Content-Type: application/json" \
  --header "Session-Token: $API_KEY" \
  --data '{
    "name": "my-session-token"
  }'

Example: get the workspaces created by a user

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/workspaces?users=$USER_ID" \
  --header "Session-Token: $API_KEY"

Example: get the workspaces built with a specific image

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
  --header "Session-Token: $API_KEY"

Example: get info about an image tag and workspaces built with it

Change latest to your tag name

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID/tags/latest" \
  --header "Session-Token: $API_KEY"

Example: get the workspaces in a specific organization

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/workspaces?orgs=$ORG_ID" \
  --header "Session-Token: $API_KEY"

Example: get the images authorized in a specific organization

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/images/?org=$ORG_ID&workspaces=false" \
  --header "Session-Token: $API_KEY"

Example: update image tags from a registry

curl --request POST \
  --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
  --header "Session-Token: $API_KEY" \
  --data "{}"

Example: update the compute resources baseline for an image

curl --request PATCH \
  --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
  --header "Session-Token: $API_KEY" \
  --data "{
      \"default_memory_gb\": 8,
      \"description\": \"3/26/22 increased RAM from 4 to 8 GB\"
  }"

Example: import a container image

curl --request POST \
  --url "$ACCESS_URL/$API_ROUTE/images" \
  --header "Session-Token: $API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
  \"default_cpu_cores\": 4,
  \"default_disk_gb\": 4,
  \"default_memory_gb\": 10,
  \"description\": \"IntelliJ 2020.3.4\",
  \"org_id\": \"$ORG_ID\",
  \"registry_id\": \"$REG_ID\",
  \"repository\": \"marktmilligan/intellij-ultimate\",
  \"tag\": \"2020.3.4\"
}"

Example: deprecate an image (and its tags)

curl --request PATCH \
  --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
  --header "Session-Token: $API_KEY" \
  --data "{
      \"deprecated\": true
  }"

Example: Restart/rebuild a workspace

curl --request PATCH \
  --url $ACCESS_URL/$API_ROUTE/workspaces/$WS_ID \
  --header "Content-Type: application/json" \
  --header "Session-Token: $API_KEY" \
  --data "{}"

Example: How to create a user

curl --request POST \
  --url "$ACCESS_URL/$API_ROUTE/users" \
  --header "Session-Token: $API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
  \"email\": \"[email protected]\",
  \"login_type\": \"built-in\",
  \"name\": \"Bob Barker\",
  \"password\": \"password\",
  \"temporary_password\": true,
  \"username\": \"bbarker\",
  \"organizations\": [\"default\",\"$ORG_ID\"]
}"

Example: Get a user's public SSH key

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/users/$USER_ID/sshkey" \
  --header "Session-Token: $API_KEY"

Example: Create a dev URL

curl --request POST \
  --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \
  --header "Session-Token: $API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
  \"access\": \"PRIVATE\",
  \"name\": \"phpapp4\",
  \"port\": 1029,
  \"scheme\": \"http\"
}"

Example: Update a dev URL including access control level

curl --request PUT \
  --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP" \
  --header "Session-Token: $API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
  \"access\": \"AUTHED\",
  \"name\": \"phpapp4\",
  \"port\": 1029,
  \"scheme\": \"http\"
}"

Example: List dev URLs

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \
  --header "Session-Token: $API_KEY"

Example: Delete a dev URL

curl --request DELETE \
  --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP \
  --header "Session-Token: $API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
}"

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