New
The Gartner Hype Cycle Emerging Technologies Report is out!

Download now

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:

  1. If you haven't already, authenticate your CLI with your workspace.

  2. Run coder tokens create <TOKEN_NAME>

  3. 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 users in 1 month increments from Jan to March 2022

Other intervals include 1 week, 1 year, 90 day

curl --request GET \
  --url "$ACCESS_URL/$API_ROUTE/metrics/usage/active-users?\
start=2022-01-01T00:00:00.000000Z&end=2022-03-31T00:00:00.000000Z\
&interval=1 month" \
--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.