docs: API users (#5620)

* docs: audit, deploymentconfig, files, parameters * Swagger comments in workspacebuilds.go * structs in workspacebuilds.go * workspaceagents: instance identity * workspaceagents.go in progress * workspaceagents.go in progress * Agents * workspacebuilds.go * /workspaces * templates.go, templateversions.go * templateversion.go in progress * cancel * templateversions * wip * Merge * x-apidocgen * NullTime hack not needed anymore * Fix: x-apidocgen * Members * Fixes * Fix * WIP * WIP * Users * Logout * User profile * Status suspend activate * User roles * User tokens * Keys * SSH key * All * Typo * Fix * Fix * Fix: LoginWithPasswordRequest
2026-09-24 15:04:27 +08:00 · 2023-01-11 14:08:04 +01:00
parent 84120767a7
commit 8e9cbdd71b
27 changed files with 4469 additions and 113 deletions
@@ -62,7 +62,7 @@ curl -X GET http://coder-server:8080/api/v2/audit?q=string \
      "user": {
        "avatar_url": "http://example.com",
        "created_at": "2019-08-24T14:15:22Z",
-        "email": "string",
+        "email": "user@example.com",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "last_seen_at": "2019-08-24T14:15:22Z",
        "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -67,3 +67,50 @@ curl -X POST http://coder-server:8080/api/v2/authcheck \
 | 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.AuthorizationResponse](schemas.md#codersdkauthorizationresponse) |

 To perform this operation, you must be authenticated. [Learn more](authentication.md).
+
+## Log in user
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X POST http://coder-server:8080/api/v2/users/login \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`POST /users/login`
+
+> Body parameter
+
+```json
+{
+  "email": "user@example.com",
+  "password": "string"
+}
+```
+
+### Parameters
+
+| Name   | In   | Type                                                                             | Required | Description   |
+| ------ | ---- | -------------------------------------------------------------------------------- | -------- | ------------- |
+| `body` | body | [codersdk.LoginWithPasswordRequest](schemas.md#codersdkloginwithpasswordrequest) | true     | Login request |
+
+### Example responses
+
+> 201 Response
+
+```json
+{
+  "session_token": "string"
+}
+```
+
+### Responses
+
+| Status | Meaning                                                      | Description | Schema                                                                             |
+| ------ | ------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------- |
+| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created     | [codersdk.LoginWithPasswordResponse](schemas.md#codersdkloginwithpasswordresponse) |
+
+To perform this operation, you must be authenticated. [Learn more](authentication.md).
@@ -2,6 +2,150 @@

 > This page is incomplete, stay tuned.

+## Get workspace build by user, workspace name, and build number
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacename}/builds/{buildnumber} \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`GET /users/{user}/workspace/{workspacename}/builds/{buildnumber}`
+
+### Parameters
+
+| Name            | In   | Type           | Required | Description          |
+| --------------- | ---- | -------------- | -------- | -------------------- |
+| `user`          | path | string         | true     | User ID, name, or me |
+| `workspacename` | path | string         | true     | Workspace name       |
+| `buildnumber`   | path | string(number) | true     | Build number         |
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "build_number": 0,
+  "created_at": "2019-08-24T14:15:22Z",
+  "daily_cost": 0,
+  "deadline": "2019-08-24T14:15:22Z",
+  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
+  "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
+  "initiator_name": "string",
+  "job": {
+    "canceled_at": "2019-08-24T14:15:22Z",
+    "completed_at": "2019-08-24T14:15:22Z",
+    "created_at": "2019-08-24T14:15:22Z",
+    "error": "string",
+    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
+    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
+    "started_at": "2019-08-24T14:15:22Z",
+    "status": "pending",
+    "tags": {
+      "property1": "string",
+      "property2": "string"
+    },
+    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
+  },
+  "reason": "initiator",
+  "resources": [
+    {
+      "agents": [
+        {
+          "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,
+              "url": "string"
+            }
+          ],
+          "architecture": "string",
+          "connection_timeout_seconds": 0,
+          "created_at": "2019-08-24T14:15:22Z",
+          "directory": "string",
+          "disconnected_at": "2019-08-24T14:15:22Z",
+          "environment_variables": {
+            "property1": "string",
+            "property2": "string"
+          },
+          "first_connected_at": "2019-08-24T14:15:22Z",
+          "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
+            }
+          },
+          "name": "string",
+          "operating_system": "string",
+          "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
+          "startup_script": "string",
+          "status": "connecting",
+          "troubleshooting_url": "string",
+          "updated_at": "2019-08-24T14:15:22Z",
+          "version": "string"
+        }
+      ],
+      "created_at": "2019-08-24T14:15:22Z",
+      "daily_cost": 0,
+      "hide": true,
+      "icon": "string",
+      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
+      "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
+      "metadata": [
+        {
+          "key": "string",
+          "sensitive": true,
+          "value": "string"
+        }
+      ],
+      "name": "string",
+      "type": "string",
+      "workspace_transition": "start"
+    }
+  ],
+  "status": "pending",
+  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
+  "template_version_name": "string",
+  "transition": "start",
+  "updated_at": "2019-08-24T14:15:22Z",
+  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
+  "workspace_name": "string",
+  "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
+  "workspace_owner_name": "string"
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                       |
+| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.WorkspaceBuild](schemas.md#codersdkworkspacebuild) |
+
+To perform this operation, you must be authenticated. [Learn more](authentication.md).
+
 ## Get workspace build

 ### Code samples
@@ -78,11 +78,11 @@ curl -X PUT http://coder-server:8080/api/v2/organizations/{organization}/members

 ### Parameters

-| Name           | In   | Type                                                   | Required | Description           |
-| -------------- | ---- | ------------------------------------------------------ | -------- | --------------------- |
-| `organization` | path | string                                                 | true     | Organization ID       |
-| `user`         | path | string                                                 | true     | Username, UUID, or me |
-| `body`         | body | [codersdk.UpdateRoles](schemas.md#codersdkupdateroles) | true     | Update roles request  |
+| Name           | In   | Type                                                   | Required | Description          |
+| -------------- | ---- | ------------------------------------------------------ | -------- | -------------------- |
+| `organization` | path | string                                                 | true     | Organization ID      |
+| `user`         | path | string                                                 | true     | User ID, name, or me |
+| `body`         | body | [codersdk.UpdateRoles](schemas.md#codersdkupdateroles) | true     | Update roles request |

 ### Example responses

@@ -110,3 +110,49 @@ curl -X PUT http://coder-server:8080/api/v2/organizations/{organization}/members
 | 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.OrganizationMember](schemas.md#codersdkorganizationmember) |

 To perform this operation, you must be authenticated. [Learn more](authentication.md).
+
+## Get site member roles
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/users/roles \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`GET /users/roles`
+
+### Example responses
+
+> 200 Response
+
+```json
+[
+  {
+    "assignable": true,
+    "display_name": "string",
+    "name": "string"
+  }
+]
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                                  |
+| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | array of [codersdk.AssignableRoles](schemas.md#codersdkassignableroles) |
+
+<h3 id="get-site-member-roles-responseschema">Response Schema</h3>
+
+Status Code **200**
+
+| Name             | Type    | Required | Restrictions | Description |
+| ---------------- | ------- | -------- | ------------ | ----------- |
+| `[array item]`   | array   | false    |              |             |
+| `» assignable`   | boolean | false    |              |             |
+| `» display_name` | string  | false    |              |             |
+| `» name`         | string  | false    |              |             |
+
+To perform this operation, you must be authenticated. [Learn more](authentication.md).
@@ -16,6 +16,62 @@
 | ------------ | ------ | -------- | ------------ | ----------- |
 | `csp-report` | object | false    |              |             |

+## codersdk.APIKey
+
+```json
+{
+  "created_at": "2019-08-24T14:15:22Z",
+  "expires_at": "2019-08-24T14:15:22Z",
+  "id": "string",
+  "last_used": "2019-08-24T14:15:22Z",
+  "lifetime_seconds": 0,
+  "login_type": "password",
+  "scope": "all",
+  "updated_at": "2019-08-24T14:15:22Z",
+  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
+}
+```
+
+### Properties
+
+| Name               | Type                                         | Required | Restrictions | Description                                 |
+| ------------------ | -------------------------------------------- | -------- | ------------ | ------------------------------------------- |
+| `created_at`       | string                                       | true     |              |                                             |
+| `expires_at`       | string                                       | true     |              |                                             |
+| `id`               | string                                       | true     |              |                                             |
+| `last_used`        | string                                       | true     |              |                                             |
+| `lifetime_seconds` | integer                                      | true     |              |                                             |
+| `login_type`       | [codersdk.LoginType](#codersdklogintype)     | true     |              |                                             |
+| `scope`            | [codersdk.APIKeyScope](#codersdkapikeyscope) | true     |              |                                             |
+| `updated_at`       | string                                       | true     |              |                                             |
+| `user_id`          | string                                       | true     |              | User ID do not ever return the HashedSecret |
+
+#### Enumerated Values
+
+| Property     | Value                 |
+| ------------ | --------------------- |
+| `login_type` | `password`            |
+| `login_type` | `github`              |
+| `login_type` | `oidc`                |
+| `login_type` | `token`               |
+| `scope`      | `all`                 |
+| `scope`      | `application_connect` |
+
+## codersdk.APIKeyScope
+
+```json
+"all"
+```
+
+### Properties
+
+#### Enumerated Values
+
+| Value                 |
+| --------------------- |
+| `all`                 |
+| `application_connect` |
+
 ## codersdk.AWSInstanceIdentityToken

 ```json
@@ -201,7 +257,7 @@
  "user": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
-    "email": "string",
+    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -277,7 +333,7 @@
      "user": {
        "avatar_url": "http://example.com",
        "created_at": "2019-08-24T14:15:22Z",
-        "email": "string",
+        "email": "user@example.com",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "last_seen_at": "2019-08-24T14:15:22Z",
        "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -304,6 +360,24 @@
 | `audit_logs` | array of [codersdk.AuditLog](#codersdkauditlog) | false    |              |             |
 | `count`      | integer                                         | false    |              |             |

+## codersdk.AuthMethods
+
+```json
+{
+  "github": true,
+  "oidc": true,
+  "password": true
+}
+```
+
+### Properties
+
+| Name       | Type    | Required | Restrictions | Description |
+| ---------- | ------- | -------- | ------------ | ----------- |
+| `github`   | boolean | false    |              |             |
+| `oidc`     | boolean | false    |              |             |
+| `password` | boolean | false    |              |             |
+
 ## codersdk.AuthorizationCheck

 ```json
@@ -455,6 +529,42 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in
 | `autostart` |
 | `autostop`  |

+## codersdk.CreateFirstUserRequest
+
+```json
+{
+  "email": "string",
+  "password": "string",
+  "trial": true,
+  "username": "string"
+}
+```
+
+### Properties
+
+| Name       | Type    | Required | Restrictions | Description |
+| ---------- | ------- | -------- | ------------ | ----------- |
+| `email`    | string  | true     |              |             |
+| `password` | string  | true     |              |             |
+| `trial`    | boolean | false    |              |             |
+| `username` | string  | true     |              |             |
+
+## codersdk.CreateFirstUserResponse
+
+```json
+{
+  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
+  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
+}
+```
+
+### Properties
+
+| Name              | Type   | Required | Restrictions | Description |
+| ----------------- | ------ | -------- | ------------ | ----------- |
+| `organization_id` | string | false    |              |             |
+| `user_id`         | string | false    |              |             |
+
 ## codersdk.CreateOrganizationRequest

 ```json
@@ -603,6 +713,49 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | `resource_type` | `api_key`          |
 | `resource_type` | `group`            |

+## codersdk.CreateTokenRequest
+
+```json
+{
+  "lifetime": 0,
+  "scope": "all"
+}
+```
+
+### Properties
+
+| Name       | Type                                         | Required | Restrictions | Description |
+| ---------- | -------------------------------------------- | -------- | ------------ | ----------- |
+| `lifetime` | integer                                      | false    |              |             |
+| `scope`    | [codersdk.APIKeyScope](#codersdkapikeyscope) | false    |              |             |
+
+#### Enumerated Values
+
+| Property | Value                 |
+| -------- | --------------------- |
+| `scope`  | `all`                 |
+| `scope`  | `application_connect` |
+
+## codersdk.CreateUserRequest
+
+```json
+{
+  "email": "user@example.com",
+  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
+  "password": "string",
+  "username": "string"
+}
+```
+
+### Properties
+
+| Name              | Type   | Required | Restrictions | Description |
+| ----------------- | ------ | -------- | ------------ | ----------- |
+| `email`           | string | true     |              |             |
+| `organization_id` | string | true     |              |             |
+| `password`        | string | true     |              |             |
+| `username`        | string | true     |              |             |
+
 ## codersdk.CreateWorkspaceBuildRequest

 ```json
@@ -1995,6 +2148,20 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | `usage`      | string  | false    |              |             |
 | `value`      | integer | false    |              |             |

+## codersdk.GenerateAPIKeyResponse
+
+```json
+{
+  "key": "string"
+}
+```
+
+### Properties
+
+| Name  | Type   | Required | Restrictions | Description |
+| ----- | ------ | -------- | ------------ | ----------- |
+| `key` | string | false    |              |             |
+
 ## codersdk.GetAppHostResponse

 ```json
@@ -2009,6 +2176,39 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | ------ | ------ | -------- | ------------ | ------------------------------------------------------------- |
 | `host` | string | false    |              | Host is the externally accessible URL for the Coder instance. |

+## codersdk.GetUsersResponse
+
+```json
+{
+  "count": 0,
+  "users": [
+    {
+      "avatar_url": "http://example.com",
+      "created_at": "2019-08-24T14:15:22Z",
+      "email": "user@example.com",
+      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
+      "last_seen_at": "2019-08-24T14:15:22Z",
+      "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
+      "roles": [
+        {
+          "display_name": "string",
+          "name": "string"
+        }
+      ],
+      "status": "active",
+      "username": "string"
+    }
+  ]
+}
+```
+
+### Properties
+
+| Name    | Type                                    | Required | Restrictions | Description |
+| ------- | --------------------------------------- | -------- | ------------ | ----------- |
+| `count` | integer                                 | false    |              |             |
+| `users` | array of [codersdk.User](#codersdkuser) | false    |              |             |
+
 ## codersdk.GitAuthConfig

 ```json
@@ -2039,6 +2239,26 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | `type`         | string          | false    |              |             |
 | `validate_url` | string          | false    |              |             |

+## codersdk.GitSSHKey
+
+```json
+{
+  "created_at": "2019-08-24T14:15:22Z",
+  "public_key": "string",
+  "updated_at": "2019-08-24T14:15:22Z",
+  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
+}
+```
+
+### Properties
+
+| Name         | Type   | Required | Restrictions | Description |
+| ------------ | ------ | -------- | ------------ | ----------- |
+| `created_at` | string | false    |              |             |
+| `public_key` | string | false    |              |             |
+| `updated_at` | string | false    |              |             |
+| `user_id`    | string | false    |              |             |
+
 ## codersdk.GoogleInstanceIdentityToken

 ```json
@@ -2104,6 +2324,53 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | `provisioner_daemon` |
 | `provisioner`        |

+## codersdk.LoginType
+
+```json
+"password"
+```
+
+### Properties
+
+#### Enumerated Values
+
+| Value      |
+| ---------- |
+| `password` |
+| `github`   |
+| `oidc`     |
+| `token`    |
+
+## codersdk.LoginWithPasswordRequest
+
+```json
+{
+  "email": "user@example.com",
+  "password": "string"
+}
+```
+
+### Properties
+
+| Name       | Type   | Required | Restrictions | Description |
+| ---------- | ------ | -------- | ------------ | ----------- |
+| `email`    | string | true     |              |             |
+| `password` | string | true     |              |             |
+
+## codersdk.LoginWithPasswordResponse
+
+```json
+{
+  "session_token": "string"
+}
+```
+
+### Properties
+
+| Name            | Type   | Required | Restrictions | Description |
+| --------------- | ------ | -------- | ------------ | ----------- |
+| `session_token` | string | true     |              |             |
+
 ## codersdk.OAuth2Config

 ```json
@@ -3163,7 +3430,7 @@ Parameter represents a set value for the scope.
 ```json
 {
  "active_user_count": 0,
-  "active_version_id": "string",
+  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
@@ -3265,7 +3532,7 @@ Parameter represents a set value for the scope.
 {
  "description": "string",
  "icon": "string",
-  "id": "string",
+  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "markdown": "string",
  "name": "string",
  "tags": ["string"],
@@ -3293,7 +3560,7 @@ Parameter represents a set value for the scope.
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
-    "email": "string",
+    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -3412,7 +3679,7 @@ Parameter represents a set value for the scope.

 ```json
 {
-  "id": "string"
+  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
 }
 ```

@@ -3454,6 +3721,36 @@ Parameter represents a set value for the scope.
 | ------- | --------------- | -------- | ------------ | ----------- |
 | `roles` | array of string | false    |              |             |

+## codersdk.UpdateUserPasswordRequest
+
+```json
+{
+  "old_password": "string",
+  "password": "string"
+}
+```
+
+### Properties
+
+| Name           | Type   | Required | Restrictions | Description |
+| -------------- | ------ | -------- | ------------ | ----------- |
+| `old_password` | string | false    |              |             |
+| `password`     | string | true     |              |             |
+
+## codersdk.UpdateUserProfileRequest
+
+```json
+{
+  "username": "string"
+}
+```
+
+### Properties
+
+| Name       | Type   | Required | Restrictions | Description |
+| ---------- | ------ | -------- | ------------ | ----------- |
+| `username` | string | true     |              |             |
+
 ## codersdk.UpdateWorkspaceAutostartRequest

 ```json
@@ -3516,7 +3813,7 @@ Parameter represents a set value for the scope.
 {
  "avatar_url": "http://example.com",
  "created_at": "2019-08-24T14:15:22Z",
-  "email": "string",
+  "email": "user@example.com",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "last_seen_at": "2019-08-24T14:15:22Z",
  "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -29,7 +29,7 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat
 [
  {
    "active_user_count": 0,
-    "active_version_id": "string",
+    "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
    "allow_user_cancel_workspace_jobs": true,
    "build_time_stats": {
      "property1": {
@@ -72,7 +72,7 @@ Status Code **200**
 | ------------------------------------ | ---------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------ |
 | `[array item]`                       | array                                                                        | false    |              |                                            |
 | `» active_user_count`                | integer                                                                      | false    |              | ActiveUserCount is set to -1 when loading. |
-| `» active_version_id`                | string                                                                       | false    |              |                                            |
+| `» active_version_id`                | string(uuid)                                                                 | false    |              |                                            |
 | `» allow_user_cancel_workspace_jobs` | boolean                                                                      | false    |              |                                            |
 | `» build_time_stats`                 | [codersdk.TemplateBuildTimeStats](schemas.md#codersdktemplatebuildtimestats) | false    |              |                                            |
 | `»» [any property]`                  | [codersdk.TransitionStats](schemas.md#codersdktransitionstats)               | false    |              |                                            |
@@ -151,7 +151,7 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/templa
 ```json
 {
  "active_user_count": 0,
-  "active_version_id": "string",
+  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
@@ -215,7 +215,7 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat
  {
    "description": "string",
    "icon": "string",
-    "id": "string",
+    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "markdown": "string",
    "name": "string",
    "tags": ["string"],
@@ -234,16 +234,16 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat

 Status Code **200**

-| Name            | Type   | Required | Restrictions | Description |
-| --------------- | ------ | -------- | ------------ | ----------- |
-| `[array item]`  | array  | false    |              |             |
-| `» description` | string | false    |              |             |
-| `» icon`        | string | false    |              |             |
-| `» id`          | string | false    |              |             |
-| `» markdown`    | string | false    |              |             |
-| `» name`        | string | false    |              |             |
-| `» tags`        | array  | false    |              |             |
-| `» url`         | string | false    |              |             |
+| Name            | Type         | Required | Restrictions | Description |
+| --------------- | ------------ | -------- | ------------ | ----------- |
+| `[array item]`  | array        | false    |              |             |
+| `» description` | string       | false    |              |             |
+| `» icon`        | string       | false    |              |             |
+| `» id`          | string(uuid) | false    |              |             |
+| `» markdown`    | string       | false    |              |             |
+| `» name`        | string       | false    |              |             |
+| `» tags`        | array        | false    |              |             |
+| `» url`         | string       | false    |              |             |

 To perform this operation, you must be authenticated. [Learn more](authentication.md).

@@ -274,7 +274,7 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat
 ```json
 {
  "active_user_count": 0,
-  "active_version_id": "string",
+  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
@@ -358,7 +358,7 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/templa
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
-    "email": "string",
+    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -433,7 +433,7 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
-    "email": "string",
+    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -508,7 +508,7 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
-    "email": "string",
+    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -579,7 +579,7 @@ curl -X GET http://coder-server:8080/api/v2/templates/{id} \
 ```json
 {
  "active_user_count": 0,
-  "active_version_id": "string",
+  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
@@ -685,7 +685,7 @@ curl -X PATCH http://coder-server:8080/api/v2/templates/{id} \
 ```json
 {
  "active_user_count": 0,
-  "active_version_id": "string",
+  "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
  "allow_user_cancel_workspace_jobs": true,
  "build_time_stats": {
    "property1": {
@@ -778,9 +778,12 @@ curl -X GET http://coder-server:8080/api/v2/templates/{id}/versions \

 ### Parameters

-| Name | In   | Type         | Required | Description |
-| ---- | ---- | ------------ | -------- | ----------- |
-| `id` | path | string(uuid) | true     | Template ID |
+| Name       | In    | Type         | Required | Description |
+| ---------- | ----- | ------------ | -------- | ----------- |
+| `id`       | path  | string(uuid) | true     | Template ID |
+| `after_id` | query | string(uuid) | false    | After ID    |
+| `limit`    | query | integer      | false    | Page limit  |
+| `offset`   | query | integer      | false    | Page offset |

 ### Example responses

@@ -793,7 +796,7 @@ curl -X GET http://coder-server:8080/api/v2/templates/{id}/versions \
    "created_by": {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
-      "email": "string",
+      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "last_seen_at": "2019-08-24T14:15:22Z",
      "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -848,7 +851,7 @@ Status Code **200**
 | `» created_by`        | [codersdk.User](schemas.md#codersdkuser)                                 | false    |              |             |
 | `»» avatar_url`       | string(uri)                                                              | false    |              |             |
 | `»» created_at`       | string(date-time)                                                        | true     |              |             |
-| `»» email`            | string                                                                   | true     |              |             |
+| `»» email`            | string(email)                                                            | true     |              |             |
 | `»» id`               | string(uuid)                                                             | true     |              |             |
 | `»» last_seen_at`     | string(date-time)                                                        | false    |              |             |
 | `»» organization_ids` | array                                                                    | false    |              |             |
@@ -909,7 +912,7 @@ curl -X PATCH http://coder-server:8080/api/v2/templates/{id}/versions \

 ```json
 {
-  "id": "string"
+  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
 }
 ```

@@ -976,7 +979,7 @@ curl -X GET http://coder-server:8080/api/v2/templates/{id}/versions/{templatever
    "created_by": {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
-      "email": "string",
+      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "last_seen_at": "2019-08-24T14:15:22Z",
      "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -1031,7 +1034,7 @@ Status Code **200**
 | `» created_by`        | [codersdk.User](schemas.md#codersdkuser)                                 | false    |              |             |
 | `»» avatar_url`       | string(uri)                                                              | false    |              |             |
 | `»» created_at`       | string(date-time)                                                        | true     |              |             |
-| `»» email`            | string                                                                   | true     |              |             |
+| `»» email`            | string(email)                                                            | true     |              |             |
 | `»» id`               | string(uuid)                                                             | true     |              |             |
 | `»» last_seen_at`     | string(date-time)                                                        | false    |              |             |
 | `»» organization_ids` | array                                                                    | false    |              |             |
@@ -1103,7 +1106,7 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion} \
  "created_by": {
    "avatar_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
-    "email": "string",
+    "email": "user@example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_seen_at": "2019-08-24T14:15:22Z",
    "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
@@ -162,7 +162,7 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/member

 To perform this operation, you must be authenticated. [Learn more](authentication.md).

-## Get workspace metadata by owner and workspace name
+## Get workspace metadata by user and workspace name

 ### Code samples

@@ -179,7 +179,7 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacenam

 | Name              | In    | Type    | Required | Description                                                 |
 | ----------------- | ----- | ------- | -------- | ----------------------------------------------------------- |
-| `user`            | path  | string  | true     | Owner username                                              |
+| `user`            | path  | string  | true     | User ID, name, or me                                        |
 | `workspacename`   | path  | string  | true     | Workspace name                                              |
 | `include_deleted` | query | boolean | false    | Return data instead of HTTP 404 if the workspace is deleted |

@@ -370,13 +370,17 @@
          "path": "./api/parameters.md"
        },
        {
-          "title": "Agents",
-          "path": "./api/agents.md"
+          "title": "Users",
+          "path": "./api/users.md"
        },
        {
          "title": "Builds",
          "path": "./api/builds.md"
        },
+        {
+          "title": "Agents",
+          "path": "./api/agents.md"
+        },
        {
          "title": "Schemas",
          "path": "./api/schemas.md"