selfhosted
/
coder
mirror of https://github.com/coder/coder.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 4139 additions and 375 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -483,7 +483,7 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me
cd site
yarn run format:write:only ../docs/admin/prometheus.md
coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen -not \( -path './scripts/apidocgen/node_modules' -prune \) -type f) $(wildcard coderd/*.go) $(wildcard codersdk/*.go) .swaggo
coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen -not \( -path './scripts/apidocgen/node_modules' -prune \) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) .swaggo
./scripts/apidocgen/generate.sh
cd site
yarn run format:write:only ../docs/api ../docs/manifest.json ../coderd/apidoc/swagger.json

1073
coderd/apidoc/docs.go
View File

File diff suppressed because it is too large Load Diff

974
coderd/apidoc/swagger.json
View File

File diff suppressed because it is too large Load Diff

4
codersdk/apikey.go
View File

@ -10,9 +10,9 @@ import (
"github.com/google/uuid"
)
// APIKey: do not ever return the HashedSecret
type APIKey struct {
ID string `json:"id" validate:"required"`
// NOTE: do not ever return the HashedSecret
ID string `json:"id" validate:"required"`
UserID uuid.UUID `json:"user_id" validate:"required" format:"uuid"`
LastUsed time.Time `json:"last_used" validate:"required" format:"date-time"`
ExpiresAt time.Time `json:"expires_at" validate:"required" format:"date-time"`

4
codersdk/groups.go
View File

@ -17,9 +17,9 @@ type CreateGroupRequest struct {
}
type Group struct {
ID uuid.UUID `json:"id"`
ID uuid.UUID `json:"id" format:"uuid"`
Name string `json:"name"`
OrganizationID uuid.UUID `json:"organization_id"`
OrganizationID uuid.UUID `json:"organization_id" format:"uuid"`
Members []User `json:"members"`
AvatarURL string `json:"avatar_url"`
QuotaAllowance int `json:"quota_allowance"`

4
codersdk/licenses.go
View File

@ -16,8 +16,8 @@ type AddLicenseRequest struct {
type License struct {
ID int32 `json:"id"`
UUID uuid.UUID `json:"uuid"`
UploadedAt time.Time `json:"uploaded_at"`
UUID uuid.UUID `json:"uuid" format:"uuid"`
UploadedAt time.Time `json:"uploaded_at" format:"date-time"`
// Claims are the JWT claims asserted by the license. Here we use
// a generic string map to ensure that all data from the server is
// parsed verbatim, not just the fields this version of Coder

6
codersdk/provisionerdaemons.go
View File

@ -37,9 +37,9 @@ const (
)
type ProvisionerDaemon struct {
ID uuid.UUID `json:"id"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt sql.NullTime `json:"updated_at"`
ID uuid.UUID `json:"id" format:"uuid"`
CreatedAt time.Time `json:"created_at" format:"date-time"`
UpdatedAt sql.NullTime `json:"updated_at" format:"date-time"`
Name string `json:"name"`
Provisioners []ProvisionerType `json:"provisioners"`
Tags map[string]string `json:"tags"`

8
codersdk/replicas.go
View File

@ -12,16 +12,16 @@ import (
type Replica struct {
// ID is the unique identifier for the replica.
ID uuid.UUID `json:"id"`
ID uuid.UUID `json:"id" format:"uuid"`
// Hostname is the hostname of the replica.
Hostname string `json:"hostname"`
// CreatedAt is when the replica was first seen.
CreatedAt time.Time `json:"created_at"`
// CreatedAt is the timestamp when the replica was first seen.
CreatedAt time.Time `json:"created_at" format:"date-time"`
// RelayAddress is the accessible address to relay DERP connections.
RelayAddress string `json:"relay_address"`
// RegionID is the region of the replica.
RegionID int32 `json:"region_id"`
// Error is the error.
// Error is the replica error.
Error string `json:"error"`
// DatabaseLatency is the latency in microseconds to the database.
DatabaseLatency int32 `json:"database_latency"`

4
codersdk/templates.go
View File

@ -60,12 +60,12 @@ type TemplateACL struct {
type TemplateGroup struct {
Group
Role TemplateRole `json:"role"`
Role TemplateRole `json:"role" enums:"admin,use"`
}
type TemplateUser struct {
User
Role TemplateRole `json:"role"`
Role TemplateRole `json:"role" enums:"admin,use"`
}
type UpdateTemplateACL struct {

280
docs/api/builds.md
View File

@ -515,61 +515,61 @@ curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/res
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
@ -884,91 +884,91 @@ curl -X GET http://coder-server:8080/api/v2/workspaces/{id}/builds \
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» build_number` | integer | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» deadline` | string(date-time) | false | | |
| `» id` | string(uuid) | false | | |
| `» initiator_id` | string(uuid) | false | | |
| `» initiator_name` | string | false | | |
| `» job` | [codersdk.ProvisionerJob](schemas.md#codersdkprovisionerjob) | false | | |
| `»» canceled_at` | string(date-time) | false | | |
| `»» completed_at` | string(date-time) | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» error` | string | false | | |
| `»» file_id` | string(uuid) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» started_at` | string(date-time) | false | | |
| `»» status` | [codersdk.ProvisionerJobStatus](schemas.md#codersdkprovisionerjobstatus) | false | | |
| `»» tags` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» worker_id` | string(uuid) | false | | |
| `» reason` | [codersdk.BuildReason](schemas.md#codersdkbuildreason) | false | | |
| `» resources` | 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 | | |
| `» status` | [codersdk.WorkspaceStatus](schemas.md#codersdkworkspacestatus) | false | | |
| `» template_version_id` | string(uuid) | false | | |
| `» template_version_name` | string | false | | |
| `» transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» workspace_id` | string(uuid) | false | | |
| `» workspace_name` | string | false | | |
| `» workspace_owner_id` | string(uuid) | false | | |
| `» workspace_owner_name` | string | false | | |
| Name | Type | Required | Restrictions | Description |
| -------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[array item]` | array | false | | |
| `» build_number` | integer | false | | |
| `» created_at` | string(date-time) | false | | |
| `» daily_cost` | integer | false | | |
| `» deadline` | string(date-time) | false | | |
| `» id` | string(uuid) | false | | |
| `» initiator_id` | string(uuid) | false | | |
| `» initiator_name` | string | false | | |
| `» job` | [codersdk.ProvisionerJob](schemas.md#codersdkprovisionerjob) | false | | |
| `»» canceled_at` | string(date-time) | false | | |
| `»» completed_at` | string(date-time) | false | | |
| `»» created_at` | string(date-time) | false | | |
| `»» error` | string | false | | |
| `»» file_id` | string(uuid) | false | | |
| `»» id` | string(uuid) | false | | |
| `»» started_at` | string(date-time) | false | | |
| `»» status` | [codersdk.ProvisionerJobStatus](schemas.md#codersdkprovisionerjobstatus) | false | | |
| `»» tags` | object | false | | |
| `»»» [any property]` | string | false | | |
| `»» worker_id` | string(uuid) | false | | |
| `» reason` | [codersdk.BuildReason](schemas.md#codersdkbuildreason) | false | | |
| `» resources` | 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 | | |
| `» status` | [codersdk.WorkspaceStatus](schemas.md#codersdkworkspacestatus) | false | | |
| `» template_version_id` | string(uuid) | false | | |
| `» template_version_name` | string | false | | |
| `» transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
| `» updated_at` | string(date-time) | false | | |
| `» workspace_id` | string(uuid) | false | | |
| `» workspace_name` | string | false | | |
| `» workspace_owner_id` | string(uuid) | false | | |
| `» workspace_owner_name` | string | false | | |
#### Enumerated Values

980
docs/api/enterprise.md Normal file
View File

@ -0,0 +1,980 @@
# Enterprise
> This page is incomplete, stay tuned.
## Get appearance
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/appearance \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /appearance`
### Example responses
> 200 Response
```json
{
"logo_url": "string",
"service_banner": {
"background_color": "string",
"enabled": true,
"message": "string"
}
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AppearanceConfig](schemas.md#codersdkappearanceconfig) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Update appearance
### Code samples
```shell
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/appearance \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /appearance`
> Body parameter
```json
{
"logo_url": "string",
"service_banner": {
"background_color": "string",
"enabled": true,
"message": "string"
}
}
```
### Parameters
| Name | In | Type | Required | Description |
| ------ | ---- | ---------------------------------------------------------------- | -------- | ------------------------- |
| `body` | body | [codersdk.AppearanceConfig](schemas.md#codersdkappearanceconfig) | true | Update appearance request |
### Example responses
> 200 Response
```json
{
"logo_url": "string",
"service_banner": {
"background_color": "string",
"enabled": true,
"message": "string"
}
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AppearanceConfig](schemas.md#codersdkappearanceconfig) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get entitlements
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/entitlements \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /entitlements`
### Example responses
> 200 Response
```json
{
"errors": ["string"],
"experimental": true,
"features": {
"property1": {
"actual": 0,
"enabled": true,
"entitlement": "entitled",
"limit": 0
},
"property2": {
"actual": 0,
"enabled": true,
"entitlement": "entitled",
"limit": 0
}
},
"has_license": true,
"trial": true,
"warnings": ["string"]
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Entitlements](schemas.md#codersdkentitlements) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get groups
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /groups`
### Parameters
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
### Example responses
> 200 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 |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Group](schemas.md#codersdkgroup) |
<h3 id="get-groups-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --------------------- | ---------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» avatar_url` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» members` | array | false | | |
| `»» avatar_url` | string(uri) | false | | |
| `»» created_at` | string(date-time) | true | | |
| `»» email` | string(email) | true | | |
| `»» id` | string(uuid) | true | | |
| `»» last_seen_at` | string(date-time) | false | | |
| `»» organization_ids` | array | false | | |
| `»» roles` | array | false | | |
| `»»» display_name` | string | false | | |
| `»»» name` | string | false | | |
| `»» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | |
| `»» username` | string | true | | |
| `» name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» quota_allowance` | integer | false | | |
#### Enumerated Values
| Property | Value |
| -------- | ----------- |
| `status` | `active` |
| `status` | `suspended` |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get group by name
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups/{groupName} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /groups/{groupName}`
### Parameters
| Name | In | Type | Required | Description |
| ----------- | ---- | ------ | -------- | ----------- |
| `groupName` | path | string | true | Group name |
### Example responses
> 200 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 |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Group](schemas.md#codersdkgroup) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Delete license
### Code samples
```shell
# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/license/{id} \
-H 'Coder-Session-Token: API_KEY'
```
`DELETE /license/{id}`
### Parameters
| Name | In | Type | Required | Description |
| ---- | ---- | -------------- | -------- | ----------- |
| `id` | path | string(number) | true | License ID |
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get licenses
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/licenses \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /licenses`
### Example responses
> 200 Response
```json
[
{
"claims": {},
"id": 0,
"uploaded_at": "2019-08-24T14:15:22Z",
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.License](schemas.md#codersdklicense) |
<h3 id="get-licenses-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `[array item]` | array | false | | |
| `» claims` | object | false | | Claims are the JWT claims asserted by the license. Here we use a generic string map to ensure that all data from the server is parsed verbatim, not just the fields this version of Coder understands. |
| `» id` | integer | false | | |
| `» uploaded_at` | string(date-time) | false | | |
| `» uuid` | string(uuid) | false | | |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get groups by organization
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /organizations/{organization}/groups`
### Parameters
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
### Example responses
> 200 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 |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Group](schemas.md#codersdkgroup) |
<h3 id="get-groups-by-organization-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| --------------------- | ---------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» avatar_url` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» members` | array | false | | |
| `»» avatar_url` | string(uri) | false | | |
| `»» created_at` | string(date-time) | true | | |
| `»» email` | string(email) | true | | |
| `»» id` | string(uuid) | true | | |
| `»» last_seen_at` | string(date-time) | false | | |
| `»» organization_ids` | array | false | | |
| `»» roles` | array | false | | |
| `»»» display_name` | string | false | | |
| `»»» name` | string | false | | |
| `»» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | |
| `»» username` | string | true | | |
| `» name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» quota_allowance` | integer | false | | |
#### Enumerated Values
| Property | Value |
| -------- | ----------- |
| `status` | `active` |
| `status` | `suspended` |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get provisioner daemons
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerdaemons \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /organizations/{organization}/provisionerdaemons`
### Parameters
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
### Example responses
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"provisioners": ["string"],
"tags": {
"property1": "string",
"property2": "string"
},
"updated_at": {
"time": "string",
"valid": true
}
}
]
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.ProvisionerDaemon](schemas.md#codersdkprovisionerdaemon) |
<h3 id="get-provisioner-daemons-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ------------------- | -------------------------------------- | -------- | ------------ | --------------------------------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | false | | |
| `» id` | string(uuid) | false | | |
| `» name` | string | false | | |
| `» provisioners` | array | false | | |
| `» tags` | object | false | | |
| `»» [any property]` | string | false | | |
| `» updated_at` | [sql.NullTime](schemas.md#sqlnulltime) | false | | |
| `»» time` | string | false | | |
| `»» valid` | boolean | false | | Valid is true if Time is not NULL |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Serve provisioner daemon
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerdaemons/serve \
-H 'Coder-Session-Token: API_KEY'
```
`GET /organizations/{organization}/provisionerdaemons/serve`
### Parameters
| Name | In | Type | Required | Description |
| -------------- | ---- | ------------ | -------- | --------------- |
| `organization` | path | string(uuid) | true | Organization ID |
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------------------ | ------------------- | ------ |
| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get active replicas
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/replicas \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /replicas`
### Example responses
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"database_latency": 0,
"error": "string",
"hostname": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"region_id": 0,
"relay_address": "string"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Replica](schemas.md#codersdkreplica) |
<h3 id="get-active-replicas-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------------ |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | false | | Created at is the timestamp when the replica was first seen. |
| `» database_latency` | integer | false | | Database latency is the latency in microseconds to the database. |
| `» error` | string | false | | Error is the replica error. |
| `» hostname` | string | false | | Hostname is the hostname of the replica. |
| `» id` | string(uuid) | false | | ID is the unique identifier for the replica. |
| `» region_id` | integer | false | | Region ID is the region of the replica. |
| `» relay_address` | string | false | | Relay address is the accessible address to relay DERP connections. |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## SCIM 2.0: Create new user
### Code samples
```shell
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/scim/v2/Users \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /scim/v2/Users`
> Body parameter
```json
{
"active": true,
"emails": [
{
"display": "string",
"primary": true,
"type": "string",
"value": "user@example.com"
}
],
"groups": [null],
"id": "string",
"meta": {
"resourceType": "string"
},
"name": {
"familyName": "string",
"givenName": "string"
},
"schemas": ["string"],
"userName": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
| ------ | ---- | -------------------------------------------- | -------- | ----------- |
| `body` | body | [coderd.SCIMUser](schemas.md#coderdscimuser) | true | New user |
### Example responses
> 200 Response
```json
{
"active": true,
"emails": [
{
"display": "string",
"primary": true,
"type": "string",
"value": "user@example.com"
}
],
"groups": [null],
"id": "string",
"meta": {
"resourceType": "string"
},
"name": {
"familyName": "string",
"givenName": "string"
},
"schemas": ["string"],
"userName": "string"
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [coderd.SCIMUser](schemas.md#coderdscimuser) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## SCIM 2.0: Get user by ID
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/scim/v2/Users/{id} \
-H 'Coder-Session-Token: API_KEY'
```
`GET /scim/v2/Users/{id}`
### Parameters
| Name | In | Type | Required | Description |
| ---- | ---- | ------------ | -------- | ----------- |
| `id` | path | string(uuid) | true | User ID |
### Responses
| Status | Meaning | Description | Schema |
| ------ | -------------------------------------------------------------- | ----------- | ------ |
| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Not Found | |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## SCIM 2.0: Update user account
### Code samples
```shell
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/scim/v2/Users/{id} \
-H 'Content-Type: application/json' \
-H 'Accept: application/scim+json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /scim/v2/Users/{id}`
> Body parameter
```json
{
"active": true,
"emails": [
{
"display": "string",
"primary": true,
"type": "string",
"value": "user@example.com"
}
],
"groups": [null],
"id": "string",
"meta": {
"resourceType": "string"
},
"name": {
"familyName": "string",
"givenName": "string"
},
"schemas": ["string"],
"userName": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
| ------ | ---- | -------------------------------------------- | -------- | ------------------- |
| `id` | path | string(uuid) | true | User ID |
| `body` | body | [coderd.SCIMUser](schemas.md#coderdscimuser) | true | Update user request |
### Example responses
> 200 Response
```json
{
"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"
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.User](schemas.md#codersdkuser) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get template ACLs
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /templates/{template}/acl`
### Parameters
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------ | -------- | ----------- |
| `template` | path | string(uuid) | true | Template ID |
### Example responses
> 200 Response
```json
[
{
"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"],
"role": "admin",
"roles": [
{
"display_name": "string",
"name": "string"
}
],
"status": "active",
"username": "string"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateUser](schemas.md#codersdktemplateuser) |
<h3 id="get-template-acls-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------- | -------------------------------------------------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» avatar_url` | string(uri) | false | | |
| `» created_at` | string(date-time) | true | | |
| `» email` | string(email) | true | | |
| `» id` | string(uuid) | true | | |
| `» last_seen_at` | string(date-time) | false | | |
| `» organization_ids` | array | false | | |
| `» role` | [codersdk.TemplateRole](schemas.md#codersdktemplaterole) | false | | |
| `» roles` | array | false | | |
| `»» display_name` | string | false | | |
| `»» name` | string | false | | |
| `» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | |
| `» username` | string | true | | |
#### Enumerated Values
| Property | Value |
| -------- | ----------- |
| `role` | `admin` |
| `role` | `use` |
| `status` | `active` |
| `status` | `suspended` |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Update template ACL
### Code samples
```shell
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templates/{template}/acl \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /templates/{template}/acl`
> Body parameter
```json
{
"group_perms": {
"property1": "admin",
"property2": "admin"
},
"user_perms": {
"property1": "admin",
"property2": "admin"
}
}
```
### Parameters
| Name | In | Type | Required | Description |
| ---------- | ---- | ------------------------------------------------------------------ | -------- | ----------------------- |
| `template` | path | string(uuid) | true | Template ID |
| `body` | body | [codersdk.UpdateTemplateACL](schemas.md#codersdkupdatetemplateacl) | true | Update template request |
### Example responses
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get workspace quota by user
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspace-quota/{user} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /workspace-quota/{user}`
### Parameters
| Name | In | Type | Required | Description |
| ------ | ---- | ------ | -------- | -------------------- |
| `user` | path | string | true | User ID, name, or me |
### Example responses
> 200 Response
```json
{
"budget": 0,
"credits_consumed": 0
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceQuota](schemas.md#codersdkworkspacequota) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).

49
docs/api/organizations.md
View File

@ -2,6 +2,55 @@
> This page is incomplete, stay tuned.
## Add new license
### Code samples
```shell
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/licenses \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /licenses`
> Body parameter
```json
{
"license": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------------------------------ | -------- | ------------------- |
| `body` | body | [codersdk.AddLicenseRequest](schemas.md#codersdkaddlicenserequest) | true | Add license request |
### Example responses
> 201 Response
```json
{
"claims": {},
"id": 0,
"uploaded_at": "2019-08-24T14:15:22Z",
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------------ | ----------- | ---------------------------------------------- |
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.License](schemas.md#codersdklicense) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Create organization
### Code samples

449
docs/api/schemas.md
View File

@ -2,6 +2,53 @@
> This page is incomplete, stay tuned.
## coderd.SCIMUser
```json
{
"active": true,
"emails": [
{
"display": "string",
"primary": true,
"type": "string",
"value": "user@example.com"
}
],
"groups": [null],
"id": "string",
"meta": {
"resourceType": "string"
},
"name": {
"familyName": "string",
"givenName": "string"
},
"schemas": ["string"],
"userName": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ---------------- | ------------------ | -------- | ------------ | ----------- |
| `active` | boolean | false | | |
| `emails` | array of object | false | | |
| `» display` | string | false | | |
| `» primary` | boolean | false | | |
| `» type` | string | false | | |
| `» value` | string | false | | |
| `groups` | array of undefined | false | | |
| `id` | string | false | | |
| `meta` | object | false | | |
| `» resourceType` | string | false | | |
| `name` | object | false | | |
| `» familyName` | string | false | | |
| `» givenName` | string | false | | |
| `schemas` | array of string | false | | |
| `userName` | string | false | | |
## coderd.cspViolation
```json
@ -34,17 +81,17 @@
### 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 |
| 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 | | |
#### Enumerated Values
@ -88,6 +135,20 @@
| `document` | string | true | | |
| `signature` | string | true | | |
## codersdk.AddLicenseRequest
```json
{
"license": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| --------- | ------ | -------- | ------------ | ----------- |
| `license` | string | true | | |
## codersdk.AgentGitSSHKey
```json
@ -146,6 +207,26 @@
| ----------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------ |
| `report_interval` | integer | false | | Report interval is the duration after which the agent should send stats again. |
## codersdk.AppearanceConfig
```json
{
"logo_url": "string",
"service_banner": {
"background_color": "string",
"enabled": true,
"message": "string"
}
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ---------------- | ------------------------------------------------------------ | -------- | ------------ | ----------- |
| `logo_url` | string | false | | |
| `service_banner` | [codersdk.ServiceBannerConfig](#codersdkservicebannerconfig) | false | | |
## codersdk.AssignableRoles
```json
@ -565,6 +646,24 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in
| `organization_id` | string | false | | |
| `user_id` | string | false | | |
## codersdk.CreateGroupRequest
```json
{
"avatar_url": "string",
"name": "string",
"quota_allowance": 0
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ----------------- | ------- | -------- | ------------ | ----------- |
| `avatar_url` | string | false | | |
| `name` | string | false | | |
| `quota_allowance` | integer | false | | |
## codersdk.CreateOrganizationRequest
```json
@ -2148,6 +2247,80 @@ CreateParameterRequest is a structure used to create a new parameter value for a
| `usage` | string | false | | |
| `value` | integer | false | | |
## codersdk.Entitlement
```json
"entitled"
```
### Properties
#### Enumerated Values
| Value |
| -------------- |
| `entitled` |
| `grace_period` |
| `not_entitled` |
## codersdk.Entitlements
```json
{
"errors": ["string"],
"experimental": true,
"features": {
"property1": {
"actual": 0,
"enabled": true,
"entitlement": "entitled",
"limit": 0
},
"property2": {
"actual": 0,
"enabled": true,
"entitlement": "entitled",
"limit": 0
}
},
"has_license": true,
"trial": true,
"warnings": ["string"]
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ------------------------------------ | -------- | ------------ | ----------- |
| `errors` | array of string | false | | |
| `experimental` | boolean | false | | |
| `features` | object | false | | |
| » `[any property]` | [codersdk.Feature](#codersdkfeature) | false | | |
| `has_license` | boolean | false | | |
| `trial` | boolean | false | | |
| `warnings` | array of string | false | | |
## codersdk.Feature
```json
{
"actual": 0,
"enabled": true,
"entitlement": "entitled",
"limit": 0
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------- | -------------------------------------------- | -------- | ------------ | ----------- |
| `actual` | integer | false | | |
| `enabled` | boolean | false | | |
| `entitlement` | [codersdk.Entitlement](#codersdkentitlement) | false | | |
| `limit` | integer | false | | |
## codersdk.GenerateAPIKeyResponse
```json
@ -2273,6 +2446,47 @@ CreateParameterRequest is a structure used to create a new parameter value for a
| ---------------- | ------ | -------- | ------------ | ----------- |
| `json_web_token` | string | true | | |
## codersdk.Group
```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
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ----------------- | --------------------------------------- | -------- | ------------ | ----------- |
| `avatar_url` | string | false | | |
| `id` | string | false | | |
| `members` | array of [codersdk.User](#codersdkuser) | false | | |
| `name` | string | false | | |
| `organization_id` | string | false | | |
| `quota_allowance` | integer | false | | |
## codersdk.Healthcheck
```json
@ -2291,6 +2505,26 @@ CreateParameterRequest is a structure used to create a new parameter value for a
| `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. |
## codersdk.License
```json
{
"claims": {},
"id": 0,
"uploaded_at": "2019-08-24T14:15:22Z",
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `claims` | object | false | | Claims are the JWT claims asserted by the license. Here we use a generic string map to ensure that all data from the server is parsed verbatim, not just the fields this version of Coder understands. |
| `id` | integer | false | | |
| `uploaded_at` | string | false | | |
| `uuid` | string | false | | |
## codersdk.LogLevel
```json
@ -3010,6 +3244,37 @@ Parameter represents a set value for the scope.
| `daemons` | [codersdk.DeploymentConfigField-int](#codersdkdeploymentconfigfield-int) | false | | |
| `force_cancel_interval` | [codersdk.DeploymentConfigField-time_Duration](#codersdkdeploymentconfigfield-time_duration) | false | | |
## codersdk.ProvisionerDaemon
```json
{
"created_at": "2019-08-24T14:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"provisioners": ["string"],
"tags": {
"property1": "string",
"property2": "string"
},
"updated_at": {
"time": "string",
"valid": true
}
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ---------------------------- | -------- | ------------ | ----------- |
| `created_at` | string | false | | |
| `id` | string | false | | |
| `name` | string | false | | |
| `provisioners` | array of string | false | | |
| `tags` | object | false | | |
| » `[any property]` | string | false | | |
| `updated_at` | [sql.NullTime](#sqlnulltime) | false | | |
## codersdk.ProvisionerJob
```json
@ -3160,6 +3425,32 @@ Parameter represents a set value for the scope.
| `api` | [codersdk.DeploymentConfigField-int](#codersdkdeploymentconfigfield-int) | false | | |
| `disable_all` | [codersdk.DeploymentConfigField-bool](#codersdkdeploymentconfigfield-bool) | false | | |
## codersdk.Replica
```json
{
"created_at": "2019-08-24T14:15:22Z",
"database_latency": 0,
"error": "string",
"hostname": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"region_id": 0,
"relay_address": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ------- | -------- | ------------ | ------------------------------------------------------------------ |
| `created_at` | string | false | | Created at is the timestamp when the replica was first seen. |
| `database_latency` | integer | false | | Database latency is the latency in microseconds to the database. |
| `error` | string | false | | Error is the replica error. |
| `hostname` | string | false | | Hostname is the hostname of the replica. |
| `id` | string | false | | ID is the unique identifier for the replica. |
| `region_id` | integer | false | | Region ID is the region of the replica. |
| `relay_address` | string | false | | Relay address is the accessible address to relay DERP connections. |
## codersdk.ResourceType
```json
@ -3221,6 +3512,24 @@ Parameter represents a set value for the scope.
| `display_name` | string | false | | |
| `name` | string | false | | |
## codersdk.ServiceBannerConfig
```json
{
"background_color": "string",
"enabled": true,
"message": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ------- | -------- | ------------ | ----------- |
| `background_color` | string | false | | |
| `enabled` | boolean | false | | |
| `message` | string | false | | |
## codersdk.SwaggerConfig
```json
@ -3552,6 +3861,68 @@ Parameter represents a set value for the scope.
| `tags` | array of string | false | | |
| `url` | string | false | | |
## codersdk.TemplateRole
```json
"admin"
```
### Properties
#### Enumerated Values
| Value |
| ------- |
| `admin` |
| `use` |
| `` |
## codersdk.TemplateUser
```json
{
"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"],
"role": "admin",
"roles": [
{
"display_name": "string",
"name": "string"
}
],
"status": "active",
"username": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ---------------------------------------------- | -------- | ------------ | ----------- |
| `avatar_url` | string | false | | |
| `created_at` | string | true | | |
| `email` | string | true | | |
| `id` | string | true | | |
| `last_seen_at` | string | false | | |
| `organization_ids` | array of string | false | | |
| `role` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | |
| `roles` | array of [codersdk.Role](#codersdkrole) | false | | |
| `status` | [codersdk.UserStatus](#codersdkuserstatus) | false | | |
| `username` | string | true | | |
#### Enumerated Values
| Property | Value |
| -------- | ----------- |
| `role` | `admin` |
| `role` | `use` |
| `status` | `active` |
| `status` | `suspended` |
## codersdk.TemplateVersion
```json
@ -3721,6 +4092,30 @@ Parameter represents a set value for the scope.
| ------- | --------------- | -------- | ------------ | ----------- |
| `roles` | array of string | false | | |
## codersdk.UpdateTemplateACL
```json
{
"group_perms": {
"property1": "admin",
"property2": "admin"
},
"user_perms": {
"property1": "admin",
"property2": "admin"
}
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ---------------------------------------------- | -------- | ------------ | ----------- |
| `group_perms` | object | false | | |
| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | |
| `user_perms` | object | false | | |
| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | |
## codersdk.UpdateUserPasswordRequest
```json
@ -4510,6 +4905,22 @@ Parameter represents a set value for the scope.
| `transition` | `stop` |
| `transition` | `delete` |
## codersdk.WorkspaceQuota
```json
{
"budget": 0,
"credits_consumed": 0
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ------- | -------- | ------------ | ----------- |
| `budget` | integer | false | | |
| `credits_consumed` | integer | false | | |
## codersdk.WorkspaceResource
```json
@ -4887,6 +5298,22 @@ Parameter represents a set value for the scope.
| `source_value` | string | false | | |
| `updated_at` | string | false | | |
## sql.NullTime
```json
{
"time": "string",
"valid": true
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------- | ------- | -------- | ------------ | --------------------------------- |
| `time` | string | false | | |
| `valid` | boolean | false | | Valid is true if Time is not NULL |
## tailcfg.DERPMap
```json

377
docs/api/templates.md
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

24
docs/api/users.md
View File

@ -587,18 +587,18 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/keys/tokens \
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------------- | ------------------------------------------------------ | -------- | ------------ | ----------------------------------------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | true | | |
| `» expires_at` | string(date-time) | true | | |
| `» id` | string | true | | |
| `» last_used` | string(date-time) | true | | |
| `» lifetime_seconds` | integer | true | | |
| `» login_type` | [codersdk.LoginType](schemas.md#codersdklogintype) | true | | |
| `» scope` | [codersdk.APIKeyScope](schemas.md#codersdkapikeyscope) | true | | |
| `» updated_at` | string(date-time) | true | | |
| `» user_id` | string(uuid) | true | | NOTE: do not ever return the HashedSecret |
| Name | Type | Required | Restrictions | Description |
| -------------------- | ------------------------------------------------------ | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | true | | |
| `» expires_at` | string(date-time) | true | | |
| `» id` | string | true | | |
| `» last_used` | string(date-time) | true | | |
| `» lifetime_seconds` | integer | true | | |
| `» login_type` | [codersdk.LoginType](schemas.md#codersdklogintype) | true | | |
| `» scope` | [codersdk.APIKeyScope](schemas.md#codersdkapikeyscope) | true | | |
| `» updated_at` | string(date-time) | true | | |
| `» user_id` | string(uuid) | true | | |
#### Enumerated Values

72
docs/manifest.json
View File

@ -325,14 +325,14 @@
"path": "./api/index.md",
"icon_path": "./images/icons/api.svg",
"children": [
{
"title": "Authentication",
"path": "./api/authentication.md"
},
{
"title": "General",
"path": "./api/general.md"
},
{
"title": "Agents",
"path": "./api/agents.md"
},
{
"title": "Applications",
"path": "./api/applications.md"
@ -341,49 +341,53 @@
"title": "Audit",
"path": "./api/audit.md"
},
{
"title": "Authentication",
"path": "./api/authentication.md"
},
{
"title": "Authorization",
"path": "./api/authorization.md"
},
{
"title": "Files",
"path": "./api/files.md"
},
{
"title": "Organizations",
"path": "./api/organizations.md"
},
{
"title": "Members",
"path": "./api/members.md"
},
{
"title": "Workspaces",
"path": "./api/workspaces.md"
},
{
"title": "Templates",
"path": "./api/templates.md"
},
{
"title": "Parameters",
"path": "./api/parameters.md"
},
{
"title": "Users",
"path": "./api/users.md"
},
{
"title": "Builds",
"path": "./api/builds.md"
},
{
"title": "Agents",
"path": "./api/agents.md"
"title": "Enterprise",
"path": "./api/enterprise.md"
},
{
"title": "Files",
"path": "./api/files.md"
},
{
"title": "Members",
"path": "./api/members.md"
},
{
"title": "Organizations",
"path": "./api/organizations.md"
},
{
"title": "Parameters",
"path": "./api/parameters.md"
},
{
"title": "Schemas",
"path": "./api/schemas.md"
},
{
"title": "Templates",
"path": "./api/templates.md"
},
{
"title": "Users",
"path": "./api/users.md"
},
{
"title": "Workspaces",
"path": "./api/workspaces.md"
}
]
}

15
enterprise/coderd/appearance.go
View File

@ -15,6 +15,13 @@ import (
"github.com/coder/coder/codersdk"
)
// @Summary Get appearance
// @ID get-appearance
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Success 200 {object} codersdk.AppearanceConfig
// @Router /appearance [get]
func (api *API) appearance(rw http.ResponseWriter, r *http.Request) {
api.entitlementsMu.RLock()
isEntitled := api.entitlements.Features[codersdk.FeatureAppearance].Entitlement == codersdk.EntitlementEntitled
@ -74,6 +81,14 @@ func validateHexColor(color string) error {
return err
}
// @Summary Update appearance
// @ID update-appearance
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param request body codersdk.AppearanceConfig true "Update appearance request"
// @Success 200 {object} codersdk.AppearanceConfig
// @Router /appearance [put]
func (api *API) putAppearance(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()

9
enterprise/coderd/coderd.go
View File

@ -81,7 +81,7 @@ func New(ctx context.Context, options *Options) (*API, error) {
httpmw.ExtractOrganizationParam(api.Database),
)
r.Post("/", api.postGroupByOrganization)
r.Get("/", api.groups)
r.Get("/", api.groupsByOrganization)
r.Route("/{groupName}", func(r chi.Router) {
r.Use(
httpmw.ExtractGroupByNameParam(api.Database),
@ -331,6 +331,13 @@ func (api *API) updateEntitlements(ctx context.Context) error {
return nil
}
// @Summary Get entitlements
// @ID get-entitlements
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Success 200 {object} codersdk.Entitlements
// @Router /entitlements [get]
func (api *API) serveEntitlements(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
api.entitlementsMu.RLock()

38
enterprise/coderd/groups.go
View File

@ -17,6 +17,16 @@ import (
"github.com/coder/coder/codersdk"
)
// @Summary Create group for organization
// @ID create-group-for-organization
// @Security CoderSessionToken
// @Accept json
// @Produce json
// @Tags Templates
// @Param request body codersdk.CreateGroupRequest true "Create group request"
// @Param organization path string true "Organization ID"
// @Success 201 {object} codersdk.Group
// @Router /organizations/{organization}/groups [post]
func (api *API) postGroupByOrganization(rw http.ResponseWriter, r *http.Request) {
var (
ctx = r.Context()
@ -264,6 +274,14 @@ func (api *API) deleteGroup(rw http.ResponseWriter, r *http.Request) {
})
}
// @Summary Get group by name
// @ID get-group-by-name
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param groupName path string true "Group name"
// @Success 200 {object} codersdk.Group
// @Router /groups/{groupName} [get]
func (api *API) group(rw http.ResponseWriter, r *http.Request) {
var (
ctx = r.Context()
@ -284,6 +302,26 @@ func (api *API) group(rw http.ResponseWriter, r *http.Request) {
httpapi.Write(ctx, rw, http.StatusOK, convertGroup(group, users))
}
// @Summary Get groups by organization
// @ID get-groups-by-organization
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param organization path string true "Organization ID" format(uuid)
// @Success 200 {array} codersdk.Group
// @Router /organizations/{organization}/groups [get]
func (api *API) groupsByOrganization(rw http.ResponseWriter, r *http.Request) {
api.groups(rw, r)
}
// @Summary Get groups
// @ID get-groups
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param organization path string true "Organization ID" format(uuid)
// @Success 200 {array} codersdk.Group
// @Router /groups [get]
func (api *API) groups(rw http.ResponseWriter, r *http.Request) {
var (
ctx = r.Context()

24
enterprise/coderd/licenses.go
View File

@ -48,6 +48,15 @@ var Keys = map[string]ed25519.PublicKey{"2022-08-12": ed25519.PublicKey(key20220
// we generally don't want the old features to immediately break without warning. With a grace
// period on the license, features will continue to work from the old license until its grace
// period, then the users will get a warning allowing them to gracefully stop using the feature.
//
// @Summary Add new license
// @ID add-new-license
// @Security CoderSessionToken
// @Produce json
// @Tags Organizations
// @Param request body codersdk.AddLicenseRequest true "Add license request"
// @Success 201 {object} codersdk.License
// @Router /licenses [post]
func (api *API) postLicense(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
if !api.AGPL.Authorize(r, rbac.ActionCreate, rbac.ResourceLicense) {
@ -121,6 +130,13 @@ func (api *API) postLicense(rw http.ResponseWriter, r *http.Request) {
httpapi.Write(ctx, rw, http.StatusCreated, convertLicense(dl, rawClaims))
}
// @Summary Get licenses
// @ID get-licenses
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Success 200 {array} codersdk.License
// @Router /licenses [get]
func (api *API) licenses(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
licenses, err := api.Database.GetLicenses(ctx)
@ -155,6 +171,14 @@ func (api *API) licenses(rw http.ResponseWriter, r *http.Request) {
httpapi.Write(ctx, rw, http.StatusOK, sdkLicenses)
}
// @Summary Delete license
// @ID delete-license
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param id path string true "License ID" format(number)
// @Success 200
// @Router /license/{id} [delete]
func (api *API) deleteLicense(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
if !api.AGPL.Authorize(r, rbac.ActionDelete, rbac.ResourceLicense) {

17
enterprise/coderd/provisionerdaemons.go
View File

@ -45,6 +45,14 @@ func (api *API) provisionerDaemonsEnabledMW(next http.Handler) http.Handler {
})
}
// @Summary Get provisioner daemons
// @ID get-provisioner-daemons
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param organization path string true "Organization ID" format(uuid)
// @Success 200 {array} codersdk.ProvisionerDaemon
// @Router /organizations/{organization}/provisionerdaemons [get]
func (api *API) provisionerDaemons(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
org := httpmw.OrganizationParam(r)
@ -82,6 +90,15 @@ func (api *API) provisionerDaemons(rw http.ResponseWriter, r *http.Request) {
}
// Serves the provisioner daemon protobuf API over a WebSocket.
//
// @Summary Serve provisioner daemon
// @ID serve-provisioner-daemon
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param organization path string true "Organization ID" format(uuid)
// @Success 101
// @Router /organizations/{organization}/provisionerdaemons/serve [get]
func (api *API) provisionerDaemonServe(rw http.ResponseWriter, r *http.Request) {
tags := map[string]string{}
if r.URL.Query().Has("tag") {

8
enterprise/coderd/replicas.go
View File

@ -10,6 +10,14 @@ import (
)
// replicas returns the number of replicas that are active in Coder.
//
// @Summary Get active replicas
// @ID get-active-replicas
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Success 200 {array} codersdk.Replica
// @Router /replicas [get]
func (api *API) replicas(rw http.ResponseWriter, r *http.Request) {
if !api.AGPL.Authorize(r, rbac.ActionRead, rbac.ResourceReplicas) {
httpapi.ResourceNotFound(rw)

42
enterprise/coderd/scim.go
View File

@ -43,6 +43,14 @@ func (api *API) scimVerifyAuthHeader(r *http.Request) bool {
// Okta to try and create each user individually, this way we don't need to
// implement fetching users twice.
//
// @Summary SCIM 2.0: Get users
// @ID scim-get-users
// @Security CoderSessionToken
// @Produce application/scim+json
// @Tags Enterprise
// @Success 200
// @Router /scim/v2/Users [post]
//
//nolint:revive
func (api *API) scimGetUsers(rw http.ResponseWriter, r *http.Request) {
if !api.scimVerifyAuthHeader(r) {
@ -62,6 +70,19 @@ func (api *API) scimGetUsers(rw http.ResponseWriter, r *http.Request) {
// This is done to always force Okta to try and create the user, this way we
// don't need to implement fetching users twice.
//
// scimGetUsers intentionally always returns no users. This is done to always force
// Okta to try and create each user individually, this way we don't need to
// implement fetching users twice.
//
// @Summary SCIM 2.0: Get user by ID
// @ID scim-get-user-by-id
// @Security CoderSessionToken
// @Produce application/scim+json
// @Tags Enterprise
// @Param id path string true "User ID" format(uuid)
// @Failure 404
// @Router /scim/v2/Users/{id} [get]
//
//nolint:revive
func (api *API) scimGetUser(rw http.ResponseWriter, r *http.Request) {
if !api.scimVerifyAuthHeader(r) {
@ -86,7 +107,7 @@ type SCIMUser struct {
} `json:"name"`
Emails []struct {
Primary bool `json:"primary"`
Value string `json:"value"`
Value string `json:"value" format:"email"`
Type string `json:"type"`
Display string `json:"display"`
} `json:"emails"`
@ -98,6 +119,15 @@ type SCIMUser struct {
}
// scimPostUser creates a new user, or returns the existing user if it exists.
//
// @Summary SCIM 2.0: Create new user
// @ID scim-create-new-user
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param request body coderd.SCIMUser true "New user"
// @Success 200 {object} coderd.SCIMUser
// @Router /scim/v2/Users [post]
func (api *API) scimPostUser(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
if !api.scimVerifyAuthHeader(r) {
@ -144,6 +174,16 @@ func (api *API) scimPostUser(rw http.ResponseWriter, r *http.Request) {
}
// scimPatchUser supports suspending and activating users only.
//
// @Summary SCIM 2.0: Update user account
// @ID scim-update-user-status
// @Security CoderSessionToken
// @Produce application/scim+json
// @Tags Enterprise
// @Param id path string true "User ID" format(uuid)
// @Param request body coderd.SCIMUser true "Update user request"
// @Success 200 {object} codersdk.User
// @Router /scim/v2/Users/{id} [patch]
func (api *API) scimPatchUser(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
if !api.scimVerifyAuthHeader(r) {

2
enterprise/coderd/scim_test.go
View File

@ -34,7 +34,7 @@ func makeScimUser(t testing.TB) coderd.SCIMUser {
},
Emails: []struct {
Primary bool "json:\"primary\""
Value string "json:\"value\""
Value string "json:\"value\" format:\"email\""
Type string "json:\"type\""
Display string "json:\"display\""
}{

17
enterprise/coderd/templates.go
View File

@ -18,6 +18,14 @@ import (
"github.com/coder/coder/codersdk"
)
// @Summary Get template ACLs
// @ID get-template-acls
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param template path string true "Template ID" format(uuid)
// @Success 200 {array} codersdk.TemplateUser
// @Router /templates/{template}/acl [get]
func (api *API) templateACL(rw http.ResponseWriter, r *http.Request) {
var (
ctx = r.Context()
@ -92,6 +100,15 @@ func (api *API) templateACL(rw http.ResponseWriter, r *http.Request) {
})
}
// @Summary Update template ACL
// @ID update-template-acl
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param template path string true "Template ID" format(uuid)
// @Param request body codersdk.UpdateTemplateACL true "Update template request"
// @Success 200 {object} codersdk.Response
// @Router /templates/{template}/acl [patch]
func (api *API) patchTemplateACL(rw http.ResponseWriter, r *http.Request) {
var (
ctx = r.Context()

8
enterprise/coderd/workspacequota.go
View File

@ -99,6 +99,14 @@ func (c *committer) CommitQuota(
}, nil
}
// @Summary Get workspace quota by user
// @ID get-workspace-quota-by-user
// @Security CoderSessionToken
// @Produce json
// @Tags Enterprise
// @Param user path string true "User ID, name, or me"
// @Success 200 {object} codersdk.WorkspaceQuota
// @Router /workspace-quota/{user} [get]
func (api *API) workspaceQuota(rw http.ResponseWriter, r *http.Request) {
user := httpmw.UserParam(r)

2
scripts/apidocgen/generate.sh
View File

@ -20,7 +20,7 @@ log "Use temporary file: ${API_MD_TMP_FILE}"
pushd "${PROJECT_ROOT}"
go run github.com/swaggo/swag/cmd/swag@v1.8.9 init \
--generalInfo="coderd.go" \
--dir="./coderd,./codersdk" \
--dir="./coderd,./codersdk,./enterprise/coderd" \
--output="./coderd/apidoc" \
--outputTypes="go,json" \
--parseDependency=true

1
scripts/apidocgen/markdown-template/debug.def
View File

@ -1 +0,0 @@
{{= data.utils.inspect(data) }}

6
scripts/apidocgen/markdown-template/main.dot
View File

@ -53,12 +53,16 @@
const countUppercase = words[0].length - words[0].replace(/[A-Z]/g, '').length;
if (countUppercase > 1) {
let displayName = p.displayName.replace(/» \*\*additionalProperties\*\*/g, "It");
let displayName = p.displayName.replace(/» \*\*additionalProperties\*\*/g, "It").replace("» ", "");
displayName = displayName.charAt(0).toUpperCase() + displayName.replace(/_/g, " ").toLowerCase().slice(1);
description = displayName + " " + words.slice(1).join(' ');
}
return correctLetterCase(description);
}
/* Export functions that are used by other template partials. */
data.functions = {};
data.functions.renderDescription = renderDescription;
}}
{{? data.api.components && data.api.components.securitySchemes }}{{#def.security}}{{?}}

2
scripts/apidocgen/markdown-template/responses.def
View File

@ -98,7 +98,7 @@ Status Code **{{=response.status}}**
{{?}}
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=data.functions.renderDescription(p)}}|
{{~}}
{{~}}
{{?}}

13
scripts/apidocgen/postprocess/main.go
View File

@ -9,6 +9,7 @@ import (
"os"
"path"
"regexp"
"sort"
"strings"
"golang.org/x/xerrors"
@ -132,6 +133,18 @@ func writeDocs(sections [][]byte) error {
})
}
// Sort API pages
// The "General" section is expected to be always first.
sort.Slice(mdFiles, func(i, j int) bool {
if mdFiles[i].title == "General" {
return true // "General" < ... - sorted
}
if mdFiles[j].title == "General" {
return false // ... < "General" - not sorted
}
return sort.StringsAreSorted([]string{mdFiles[i].title, mdFiles[j].title})
})
// Update manifest.json
type route struct {
Title string `json:"title,omitempty"`