# Reference

## Automation

All actions possible through the Coder dashboard can also be automated.
There are several ways to extend/automate Coder:

* [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
* [CLI](/docs/@main/reference/cli/)
* [Representational State Transfer (REST) API](/docs/@main/reference/api/)
* [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
* [Agent API](/docs/@main/reference/agent-api/)

## Quickstart

Generate a token on your Coder deployment by visiting:

```sh
https://coder.example.com/settings/tokens
```

List your workspaces

```sh
# CLI
coder ls \
  --url https://coder.example.com \
  --token <your-token> \
  --output json

# REST API (with curl)
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
  -H "Coder-Session-Token: <your-token>"
```

## Documentation

We publish an [API reference](/docs/@main/reference/api/) in our documentation.
You can also enable a [Swagger endpoint](/docs/@main/reference/cli/server/#--swagger-enable) on your Coder deployment.

## Use cases

We strive to keep the following use cases up to date, but note that changes to API queries and routes can occur.
For the most recent queries and payloads, we recommend checking the relevant documentation.

### Users & Groups

* [Manage Users via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/user)
* [Manage Groups via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/group)

### Templates

* [Manage templates via Terraform or CLI](/docs/@main/templates/managing-templates/change-management/): Store all templates in git and update them in continuous integration and continuous delivery (CI/CD) pipelines.

### Workspace agents

Workspace agents have a special token that can send logs, metrics, and workspace activity.

* [Custom workspace logs](/docs/@main/reference/api/agents/#patch-workspace-agent-logs): Expose messages prior to the Coder init script running (for example, pulling image, VM starting, restoring snapshot). [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses this to show Kubernetes events, such as image pulls or ResourceQuota restrictions.

  ```sh
  curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
  -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
  -d "{
  \"logs\": [
    {
      \"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
      \"level\": \"info\",
      \"output\": \"Restoring workspace from snapshot: 05%...\"
    }
  ]
  }"
  ```

* [Manually send workspace activity](/docs/@main/reference/api/workspaces/#extend-workspace-deadline-by-id): Keep a workspace "active," even if there is not an open connection (for example, for a long-running machine learning job).

  This script uses a user token, not the agent token.
  Create one with `coder tokens create`, and set it as `CODER_SESSION_TOKEN`.
  The script needs `jq`.
  It leaves the deadline alone when the workspace already has a later one.
  This check needs the Coder database to use the UTC time zone, so that the API returns the deadline as a UTC timestamp that ends in `Z`.
  If the database uses another time zone, the script sets the deadline to one hour from now on every pass, which can shorten a later deadline.

  ```sh
  #!/bin/bash
  # Send workspace activity as long as the job is still running

  while true
  do
  if pgrep -f "my_training_script.py" > /dev/null
  then
    # Aim for a deadline one hour from now. The first date form is GNU, the second is BSD.
    deadline=$(date -u -d '+1 hour' +'%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u -v+1H +'%Y-%m-%dT%H:%M:%SZ')
    current=$(curl -fsS "https://coder.example.com/api/v2/workspaces/$CODER_WORKSPACE_ID" \
    -H "Coder-Session-Token: $CODER_SESSION_TOKEN" | jq -r '.latest_build.deadline')
    # Text comparison, so it is correct only for UTC timestamps, which end in Z.
    if [[ "$current" != *Z || "$current" < "$deadline" ]]
    then
      curl -fsS -X PUT "https://coder.example.com/api/v2/workspaces/$CODER_WORKSPACE_ID/extend" \
      -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
      -d "{
        \"deadline\": \"$deadline\"
      }"
    fi

    # Sleep for 30 minutes (1800 seconds) if the job is running
    sleep 1800
  else
    # Sleep for 1 minute (60 seconds) if the job is not running
    sleep 60
  fi
  done
  ```

  A user token used in a script is long-lived, so store it in a secret store, not in the script itself.
