Skip to content

Latest commit

 

History

History
424 lines (314 loc) · 9.54 KB

api.md

File metadata and controls

424 lines (314 loc) · 9.54 KB

API examples

Enable API Access

There is an environment variable --swagger-enable bool in running Coder with coder server or CODER_SWAGGER_ENABLE in helm or systemd

Once the deployment is restarted, the Swagger docs are available at <your Coder Access URL>/swagger

Pro tip: While navigating the Coder UI, use your browser's inspect feature to review API endpoint calls as you move around UI pages. Click network and the response tabs to see structured JSON API responses.

You can also grep or control/command-F the Go chi routes in the OSS repo to figure out API endpoints.

Firefox inspect with the Workspaces UI

Set environment variables to access url, apikey, etc. 

# your deployment's access url
export CODER_URL "http://your-access-url"
# your api key - get one at http://your-access-url/cli-auth
export CODER_SESSION_TOKEN="smh...F7t"
export API_ROUTE="api/v2"
# a workspace id
export WS_ID="4bd...da9"
# your org id (not a group, but the id for the entire deployment)
# you can retrieve your org id at http://your-access-url/api/v2/users/me
# hint hint: org IDs allow Coder to someday be multi-tenant...
export ORG_ID="a31...435"

If you're a fish lover like me, you would use this format to set environment variables: 

set -x CODER_URL "http://your-access-url"

The environment variables CODER_URL and CODER_SESSION_TOKEN can be also used with the coder CLI commands.

Curl command formats

The shorter form 

curl "$CODER_URL/$API_ROUTE/workspaces" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"

The longer form with the request type 

curl --request GET \
--url "$CODER_URL/$API_ROUTE/users/me" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Info about apikey's user including organization id which is needed for other endpoints

This is helpful to retrieve the organization_id, needed for other API calls. This endpoint also shows the last time the user was active aka last_seen-at. The user's roles are shown as well. e.g., owner, template-admin, etc. 

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/users/me" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Get deployment info (e.g., environment variables)

To get environment variables set for your Coder deployment like enterprise paid features enabled, git authentication, wildcard access url, access url, coder bind address, etc. 

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/deployment/config" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Create a workspace with a coder_parameter

curl --request POST
--url "$CODER_URL/api/v2/organizations/$ORG_ID/members/me/workspaces"
--header "Coder-Session-Token: $API_KEY"
--data '{ "name": "jupyter-lab", "rich_parameter_values": [ { "name": "Git Repo URL", "value": "https://github.com/sharkymark/pandas_automl" } ], "template_id": "'$TEMPLATE_ID'" }'

See the templates you have access to

To see details about a template, use the template id from the organizations/<org-id>/templates endpoint.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/organizations/$ORG_ID/templates" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Retrieve template details e.g., active users, updated at, max time to live

To see details about a template, use the template id from the organizations/<org-id>/templates endpoint.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/templates/$TEMPLATE_ID" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Latest template version detail including resources and startup_script details

To list the resources in a template, e.g., agents, coder_app, kubernetes_pod, metadata, and see the contents of the startup_script

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/templateversions/$TEMPLATE_VERSION_ID/resources" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Get User Info including Org Id 

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/users/me" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Create a User 

curl --request POST \
--url "$CODER_URL/api/v2/users" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN" \
  --data '{
  "email": "[email protected]",
  "organization_id": "<your org id>",
  "password": "C0der1two3",
  "username": "Mark"
}'
Daily Active Users of a template

To see the last 20 days of DAUs for a template, use the template id from the organizations/<org-id>/templates endpoint.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/templates/$TEMPLATE_ID/daus" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Groups with permissions to use and admin a template

To see which groups has permissions for a template, use the template id from the organizations/<org-id>/templates endpoint. This call also retrieves the users in the groups.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/templates/$TEMPLATE_ID/acl" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Get your workspaces 

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/workspaces?\
q=owner:me" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Get a specific user's workspaces

To see the workspaces for a user. Note the query parameter is the username, not the user email.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/workspaces?\
q=owner:$USER_NAME" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Details about a workspace

To see workspace details like its template, owner, and resources.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/workspaces/\
$WS_ID" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Show license entitlements

To see entitlements like high availability, template rbac aka groups, if a license is installed, is the experimental flag set, is it a trial?

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/entitlements\
" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Show active users

To show active users in your Coder deployment.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/users\
?status:active" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Show groups in your Coder deployment

To see groups. The query returns the members of each group.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/organizations/$ORG_ID/groups" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Show detail about a group

This includes the members and their roles.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/groups/$GROUP_ID" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Last 5 events in the Audit Logs

Adjust limit to your liking. Also see ResourceTypes and Actions.

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/audit\
?limit=5" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Users Created Count

To

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/audit/count\
?q=resource_type:user+\
action:create+" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Users created (limit 25)

To

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/audit\
?limit=25&q=resource_type:user+\
action:create+" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Workspaces created 

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/audit\
?limit=5&q=resource_type:workspace+\
action:create+" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Templates created 

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/audit\
?limit=5&q=resource_type:template+\
action:create+" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
All actions by a specific email address

To

curl --request GET \
  --url "$CODER_URL/$API_ROUTE/audit\
?limit=1&q=email:$EMAIL+" \
--header "Coder-Session-Token: $CODER_SESSION_TOKEN"
Empty

Use for next example 🍔