docs: API enterprise (#5625)

* 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

* Entitlements

* Groups

* SCIM

* Fix

* Fix

* Clean templates

* Sort API pages

* Fix: HashedSecret

* General is first
This commit is contained in:
Marcin Tojek
2023-01-11 16:05:42 +01:00
committed by GitHub
parent 8e9cbdd71b
commit d9436fab69
31 changed files with 4139 additions and 375 deletions
+224 -153
View File
@@ -2,6 +2,77 @@
> This page is incomplete, stay tuned.
## Create group for organization
### Code samples
```shell
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/groups \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /organizations/{organization}/groups`
> Body parameter
```json
{
"avatar_url": "string",
"name": "string",
"quota_allowance": 0
}
```
### Parameters
| Name | In | Type | Required | Description |
| -------------- | ---- | -------------------------------------------------------------------- | -------- | -------------------- |
| `organization` | path | string | true | Organization ID |
| `body` | body | [codersdk.CreateGroupRequest](schemas.md#codersdkcreategrouprequest) | true | Create group request |
### Example responses
> 201 Response
```json
{
"avatar_url": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"members": [
{
"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"
}
],
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"quota_allowance": 0
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------ | ----------- | ------------------------------------------ |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.Group](schemas.md#codersdkgroup) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get templates by organization
### Code samples
@@ -68,29 +139,29 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------------ | ---------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------ |
| `[array item]` | array | false | | |
| `» active_user_count` | integer | false | | ActiveUserCount is set to -1 when loading. |
| `» 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 | | |
| `»»» p50` | integer | false | | |
| `»»» p95` | integer | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by_id` | string(uuid) | false | | |
| `» created_by_name` | string | false | | |
| `» default_ttl_ms` | integer | false | | |
| `» description` | string | false | | |
| `» display_name` | string | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» provisioner` | string | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» workspace_owner_count` | integer | false | | |
| Name | Type | Required | Restrictions | Description |
| ------------------------------------ | ---------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------- |
| `[array item]` | array | false | | |
| `» active_user_count` | integer | false | | Active user count is set to -1 when loading. |
| `» 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 | | |
| `»»» p50` | integer | false | | |
| `»»» p95` | integer | false | | |
| `» created_at` | string(date-time) | false | | |
| `» created_by_id` | string(uuid) | false | | |
| `» created_by_name` | string | false | | |
| `» default_ttl_ms` | integer | false | | |
| `» description` | string | false | | |
| `» display_name` | string | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» provisioner` | string | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» workspace_owner_count` | integer | false | | |
#### Enumerated Values
@@ -1542,61 +1613,61 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/d
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» agents` | array | false | | |
| `»» apps` | array | false | | |
| `»»» command` | string | false | | |
| `»»» display_name` | string | false | | DisplayName is a friendly name for the app. |
| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on<br>the client or not. |
| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | |
| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. |
| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. |
| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. |
| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies<br>an icon to be displayed in the dashboard. |
| `»»» id` | string(uuid) | false | | |
| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | |
| `»»» slug` | string | false | | Slug is a unique identifier within the agent. |
| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the<br>`coder server` or via a hostname-based dev URL. If this is set to true<br>and there is no app wildcard configured on the server, the app will not<br>be accessible in the UI. |
| `»»» url` | string | false | | URL is the address being proxied to inside the workspace.<br>If external is specified, this will be opened on the client. |
| `»» architecture` | string | false | | |
| `»» connection_timeout_seconds` | integer | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» directory` | string | false | | |
| `»» disconnected_at` | string(date-time) | false | | |
| `»» environment_variables` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» first_connected_at` | string(date-time) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» instance_id` | string | false | | |
| `»» last_connected_at` | string(date-time) | false | | |
| `»» latency` | object | false | | DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). |
| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | |
| `»»»» latency_ms` | number | false | | |
| `»»»» preferred` | boolean | false | | |
| `»» name` | string | false | | |
| `»» operating_system` | string | false | | |
| `»» resource_id` | string(uuid) | false | | |
| `»» startup_script` | string | false | | |
| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | |
| `»» troubleshooting_url` | string | false | | |
| `»» updated_at` | string(date-time) | false | | |
| `»» version` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» hide` | boolean | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» metadata` | array | false | | |
| `»» key` | string | false | | |
| `»» sensitive` | boolean | false | | |
| `»» value` | string | false | | |
| `» name` | string | false | | |
| `» type` | string | false | | |
| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
| Name | Type | Required | Restrictions | Description |
| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» agents` | array | false | | |
| `»» apps` | array | false | | |
| `»»» command` | string | false | | |
| `»»» display_name` | string | false | | »»display name is a friendly name for the app. |
| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. |
| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | |
| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. |
| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. |
| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `»»»» url` | string | false | | »»»url specifies the endpoint to check for the app health. |
| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. |
| `»»» id` | string(uuid) | false | | |
| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | |
| `»»» slug` | string | false | | Slug is a unique identifier within the agent. |
| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. |
| `»»» url` | string | false | | »»url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. |
| `»» architecture` | string | false | | |
| `»» connection_timeout_seconds` | integer | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» directory` | string | false | | |
| `»» disconnected_at` | string(date-time) | false | | |
| `»» environment_variables` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» first_connected_at` | string(date-time) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» instance_id` | string | false | | |
| `»» last_connected_at` | string(date-time) | false | | |
| `»» latency` | object | false | | »latency is mapped by region name (e.g. "New York City", "Seattle"). |
| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | |
| `»»»» latency_ms` | number | false | | |
| `»»»» preferred` | boolean | false | | |
| `»» name` | string | false | | |
| `»» operating_system` | string | false | | |
| `»» resource_id` | string(uuid) | false | | |
| `»» startup_script` | string | false | | |
| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | |
| `»» troubleshooting_url` | string | false | | |
| `»» updated_at` | string(date-time) | false | | |
| `»» version` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» hide` | boolean | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» metadata` | array | false | | |
| `»» key` | string | false | | |
| `»» sensitive` | boolean | false | | |
| `»» value` | string | false | | |
| `» name` | string | false | | |
| `» type` | string | false | | |
| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
#### Enumerated Values
@@ -1883,61 +1954,61 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/r
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» agents` | array | false | | |
| `»» apps` | array | false | | |
| `»»» command` | string | false | | |
| `»»» display_name` | string | false | | DisplayName is a friendly name for the app. |
| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on<br>the client or not. |
| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | |
| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. |
| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. |
| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. |
| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies<br>an icon to be displayed in the dashboard. |
| `»»» id` | string(uuid) | false | | |
| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | |
| `»»» slug` | string | false | | Slug is a unique identifier within the agent. |
| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the<br>`coder server` or via a hostname-based dev URL. If this is set to true<br>and there is no app wildcard configured on the server, the app will not<br>be accessible in the UI. |
| `»»» url` | string | false | | URL is the address being proxied to inside the workspace.<br>If external is specified, this will be opened on the client. |
| `»» architecture` | string | false | | |
| `»» connection_timeout_seconds` | integer | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» directory` | string | false | | |
| `»» disconnected_at` | string(date-time) | false | | |
| `»» environment_variables` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» first_connected_at` | string(date-time) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» instance_id` | string | false | | |
| `»» last_connected_at` | string(date-time) | false | | |
| `»» latency` | object | false | | DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). |
| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | |
| `»»»» latency_ms` | number | false | | |
| `»»»» preferred` | boolean | false | | |
| `»» name` | string | false | | |
| `»» operating_system` | string | false | | |
| `»» resource_id` | string(uuid) | false | | |
| `»» startup_script` | string | false | | |
| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | |
| `»» troubleshooting_url` | string | false | | |
| `»» updated_at` | string(date-time) | false | | |
| `»» version` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» hide` | boolean | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» metadata` | array | false | | |
| `»» key` | string | false | | |
| `»» sensitive` | boolean | false | | |
| `»» value` | string | false | | |
| `» name` | string | false | | |
| `» type` | string | false | | |
| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
| Name | Type | Required | Restrictions | Description |
| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» agents` | array | false | | |
| `»» apps` | array | false | | |
| `»»» command` | string | false | | |
| `»»» display_name` | string | false | | »»display name is a friendly name for the app. |
| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. |
| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | |
| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. |
| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. |
| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `»»»» url` | string | false | | »»»url specifies the endpoint to check for the app health. |
| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. |
| `»»» id` | string(uuid) | false | | |
| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | |
| `»»» slug` | string | false | | Slug is a unique identifier within the agent. |
| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. |
| `»»» url` | string | false | | »»url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. |
| `»» architecture` | string | false | | |
| `»» connection_timeout_seconds` | integer | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» directory` | string | false | | |
| `»» disconnected_at` | string(date-time) | false | | |
| `»» environment_variables` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» first_connected_at` | string(date-time) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» instance_id` | string | false | | |
| `»» last_connected_at` | string(date-time) | false | | |
| `»» latency` | object | false | | »latency is mapped by region name (e.g. "New York City", "Seattle"). |
| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | |
| `»»»» latency_ms` | number | false | | |
| `»»»» preferred` | boolean | false | | |
| `»» name` | string | false | | |
| `»» operating_system` | string | false | | |
| `»» resource_id` | string(uuid) | false | | |
| `»» startup_script` | string | false | | |
| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | |
| `»» troubleshooting_url` | string | false | | |
| `»» updated_at` | string(date-time) | false | | |
| `»» version` | string | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» hide` | boolean | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» metadata` | array | false | | |
| `»» key` | string | false | | |
| `»» sensitive` | boolean | false | | |
| `»» value` | string | false | | |
| `» name` | string | false | | |
| `» type` | string | false | | |
| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
#### Enumerated Values
@@ -2017,26 +2088,26 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/s
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------------------ | ------------------------------------------------------------------------------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» allow_override_destination` | boolean | false | | |
| `» allow_override_source` | boolean | false | | |
| `» created_at` | string(date-time) | false | | |
| `» default_destination_scheme` | [codersdk.ParameterDestinationScheme](schemas.md#codersdkparameterdestinationscheme) | false | | |
| `» default_refresh` | string | false | | |
| `» default_source_scheme` | [codersdk.ParameterSourceScheme](schemas.md#codersdkparametersourcescheme) | false | | |
| `» default_source_value` | string | false | | |
| `» description` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» redisplay_value` | boolean | false | | |
| `» validation_condition` | string | false | | |
| `» validation_contains` | array | false | | This is a special array of items provided if the validation condition<br>explicitly states the value must be one of a set. |
| `» validation_error` | string | false | | |
| `» validation_type_system` | string | false | | |
| `» validation_value_type` | string | false | | |
| Name | Type | Required | Restrictions | Description |
| ------------------------------ | ------------------------------------------------------------------------------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» allow_override_destination` | boolean | false | | |
| `» allow_override_source` | boolean | false | | |
| `» created_at` | string(date-time) | false | | |
| `» default_destination_scheme` | [codersdk.ParameterDestinationScheme](schemas.md#codersdkparameterdestinationscheme) | false | | |
| `» default_refresh` | string | false | | |
| `» default_source_scheme` | [codersdk.ParameterSourceScheme](schemas.md#codersdkparametersourcescheme) | false | | |
| `» default_source_value` | string | false | | |
| `» description` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» job_id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» redisplay_value` | boolean | false | | |
| `» validation_condition` | string | false | | |
| `» validation_contains` | array | false | | This is a special array of items provided if the validation condition explicitly states the value must be one of a set. |
| `» validation_error` | string | false | | |
| `» validation_type_system` | string | false | | |
| `» validation_value_type` | string | false | | |
#### Enumerated Values