diff --git a/Makefile b/Makefile index 40a981afd59d8..cd7c316a4e266 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 17fac114fc91b..c103fa9ca0ec9 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -45,6 +45,65 @@ const docTemplate = `{ } } }, + "/appearance": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get appearance", + "operationId": "get-appearance", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + }, + "put": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Update appearance", + "operationId": "update-appearance", + "parameters": [ + { + "description": "Update appearance request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + } + }, "/applications/auth-redirect": { "get": { "security": [ @@ -303,6 +362,31 @@ const docTemplate = `{ } } }, + "/entitlements": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get entitlements", + "operationId": "get-entitlements", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Entitlements" + } + } + } + } + }, "/files": { "post": { "security": [ @@ -378,6 +462,172 @@ const docTemplate = `{ } } }, + "/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get groups", + "operationId": "get-groups", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + } + }, + "/groups/{groupName}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get group by name", + "operationId": "get-group-by-name", + "parameters": [ + { + "type": "string", + "description": "Group name", + "name": "groupName", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "/license/{id}": { + "delete": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Delete license", + "operationId": "delete-license", + "parameters": [ + { + "type": "string", + "format": "number", + "description": "License ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + }, + "/licenses": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get licenses", + "operationId": "get-licenses", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Organizations" + ], + "summary": "Add new license", + "operationId": "add-new-license", + "parameters": [ + { + "description": "Add license request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AddLicenseRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, "/organizations": { "post": { "security": [ @@ -449,6 +699,88 @@ const docTemplate = `{ } } }, + "/organizations/{organization}/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get groups by organization", + "operationId": "get-groups-by-organization", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Templates" + ], + "summary": "Create group for organization", + "operationId": "create-group-for-organization", + "parameters": [ + { + "description": "Create group request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateGroupRequest" + } + }, + { + "type": "string", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, "/organizations/{organization}/members/roles": { "get": { "security": [ @@ -582,6 +914,76 @@ const docTemplate = `{ } } }, + "/organizations/{organization}/provisionerdaemons": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get provisioner daemons", + "operationId": "get-provisioner-daemons", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ProvisionerDaemon" + } + } + } + } + } + }, + "/organizations/{organization}/provisionerdaemons/serve": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Serve provisioner daemon", + "operationId": "serve-provisioner-daemon", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "101": { + "description": "Switching Protocols" + } + } + } + }, "/organizations/{organization}/templates": { "get": { "security": [ @@ -904,133 +1306,271 @@ const docTemplate = `{ "required": true }, { - "type": "string", - "format": "uuid", - "description": "ID", - "name": "id", - "in": "path", - "required": true + "type": "string", + "format": "uuid", + "description": "ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Parameter" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Parameters" + ], + "summary": "Create parameter", + "operationId": "create-parameter", + "parameters": [ + { + "description": "Parameter request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateParameterRequest" + } + }, + { + "enum": [ + "template", + "workspace", + "import_job" + ], + "type": "string", + "description": "Scope", + "name": "scope", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Parameter" + } + } + } + } + }, + "/parameters/{scope}/{id}/{name}": { + "delete": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Parameters" + ], + "summary": "Delete parameter", + "operationId": "delete-parameter", + "parameters": [ + { + "enum": [ + "template", + "workspace", + "import_job" + ], + "type": "string", + "description": "Scope", + "name": "scope", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Name", + "name": "name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, + "/replicas": { + "get": { + "security": [ + { + "CoderSessionToken": [] } ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get active replicas", + "operationId": "get-active-replicas", "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { - "$ref": "#/definitions/codersdk.Parameter" + "$ref": "#/definitions/codersdk.Replica" } } } } - }, + } + }, + "/scim/v2/Users": { "post": { "security": [ { "CoderSessionToken": [] } ], - "consumes": [ - "application/json" - ], "produces": [ "application/json" ], "tags": [ - "Parameters" + "Enterprise" ], - "summary": "Create parameter", - "operationId": "create-parameter", + "summary": "SCIM 2.0: Create new user", + "operationId": "scim-create-new-user", "parameters": [ { - "description": "Parameter request", + "description": "New user", "name": "request", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/codersdk.CreateParameterRequest" + "$ref": "#/definitions/coderd.SCIMUser" } - }, - { - "enum": [ - "template", - "workspace", - "import_job" - ], - "type": "string", - "description": "Scope", - "name": "scope", - "in": "path", - "required": true - }, - { - "type": "string", - "format": "uuid", - "description": "ID", - "name": "id", - "in": "path", - "required": true } ], "responses": { - "201": { - "description": "Created", + "200": { + "description": "OK", "schema": { - "$ref": "#/definitions/codersdk.Parameter" + "$ref": "#/definitions/coderd.SCIMUser" } } } } }, - "/parameters/{scope}/{id}/{name}": { - "delete": { + "/scim/v2/Users/{id}": { + "get": { "security": [ { "CoderSessionToken": [] } ], "produces": [ - "application/json" + "application/scim+json" ], "tags": [ - "Parameters" + "Enterprise" ], - "summary": "Delete parameter", - "operationId": "delete-parameter", + "summary": "SCIM 2.0: Get user by ID", + "operationId": "scim-get-user-by-id", "parameters": [ { - "enum": [ - "template", - "workspace", - "import_job" - ], "type": "string", - "description": "Scope", - "name": "scope", + "format": "uuid", + "description": "User ID", + "name": "id", "in": "path", "required": true - }, + } + ], + "responses": { + "404": { + "description": "Not Found" + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/scim+json" + ], + "tags": [ + "Enterprise" + ], + "summary": "SCIM 2.0: Update user account", + "operationId": "scim-update-user-status", + "parameters": [ { "type": "string", "format": "uuid", - "description": "ID", + "description": "User ID", "name": "id", "in": "path", "required": true }, { - "type": "string", - "description": "Name", - "name": "name", - "in": "path", - "required": true + "description": "Update user request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } } ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/codersdk.Response" + "$ref": "#/definitions/codersdk.User" } } } @@ -1319,6 +1859,86 @@ const docTemplate = `{ } } }, + "/templates/{template}/acl": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get template ACLs", + "operationId": "get-template-acls", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.TemplateUser" + } + } + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Update template ACL", + "operationId": "update-template-acl", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + }, + { + "description": "Update template request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateTemplateACL" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, "/templateversions/{templateversion}": { "get": { "security": [ @@ -2852,6 +3472,40 @@ const docTemplate = `{ } } }, + "/workspace-quota/{user}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get workspace quota by user", + "operationId": "get-workspace-quota-by-user", + "parameters": [ + { + "type": "string", + "description": "User ID, name, or me", + "name": "user", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.WorkspaceQuota" + } + } + } + } + }, "/workspaceagents/aws-instance-identity": { "post": { "security": [ @@ -3819,6 +4473,70 @@ const docTemplate = `{ } }, "definitions": { + "coderd.SCIMUser": { + "type": "object", + "properties": { + "active": { + "type": "boolean" + }, + "emails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "display": { + "type": "string" + }, + "primary": { + "type": "boolean" + }, + "type": { + "type": "string" + }, + "value": { + "type": "string", + "format": "email" + } + } + } + }, + "groups": { + "type": "array", + "items": {} + }, + "id": { + "type": "string" + }, + "meta": { + "type": "object", + "properties": { + "resourceType": { + "type": "string" + } + } + }, + "name": { + "type": "object", + "properties": { + "familyName": { + "type": "string" + }, + "givenName": { + "type": "string" + } + } + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + }, + "userName": { + "type": "string" + } + } + }, "coderd.cspViolation": { "type": "object", "properties": { @@ -3889,7 +4607,6 @@ const docTemplate = `{ "format": "date-time" }, "user_id": { - "description": "NOTE: do not ever return the HashedSecret", "type": "string", "format": "uuid" } @@ -3921,6 +4638,17 @@ const docTemplate = `{ } } }, + "codersdk.AddLicenseRequest": { + "type": "object", + "required": [ + "license" + ], + "properties": { + "license": { + "type": "string" + } + } + }, "codersdk.AgentGitSSHKey": { "type": "object", "properties": { @@ -3973,6 +4701,17 @@ const docTemplate = `{ } } }, + "codersdk.AppearanceConfig": { + "type": "object", + "properties": { + "logo_url": { + "type": "string" + }, + "service_banner": { + "$ref": "#/definitions/codersdk.ServiceBannerConfig" + } + } + }, "codersdk.AssignableRoles": { "type": "object", "properties": { @@ -4244,9 +4983,23 @@ const docTemplate = `{ "type": "string", "format": "uuid" }, - "user_id": { - "type": "string", - "format": "uuid" + "user_id": { + "type": "string", + "format": "uuid" + } + } + }, + "codersdk.CreateGroupRequest": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "name": { + "type": "string" + }, + "quota_allowance": { + "type": "integer" } } }, @@ -4875,6 +5628,68 @@ const docTemplate = `{ } } }, + "codersdk.Entitlement": { + "type": "string", + "enum": [ + "entitled", + "grace_period", + "not_entitled" + ], + "x-enum-varnames": [ + "EntitlementEntitled", + "EntitlementGracePeriod", + "EntitlementNotEntitled" + ] + }, + "codersdk.Entitlements": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "string" + } + }, + "experimental": { + "type": "boolean" + }, + "features": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.Feature" + } + }, + "has_license": { + "type": "boolean" + }, + "trial": { + "type": "boolean" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "codersdk.Feature": { + "type": "object", + "properties": { + "actual": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "entitlement": { + "$ref": "#/definitions/codersdk.Entitlement" + }, + "limit": { + "type": "integer" + } + } + }, "codersdk.GenerateAPIKeyResponse": { "type": "object", "properties": { @@ -4972,6 +5787,34 @@ const docTemplate = `{ } } }, + "codersdk.Group": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.User" + } + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.Healthcheck": { "type": "object", "properties": { @@ -4989,6 +5832,27 @@ const docTemplate = `{ } } }, + "codersdk.License": { + "type": "object", + "properties": { + "claims": { + "description": "Claims are the JWT claims asserted by the license. Here we use\na generic string map to ensure that all data from the server is\nparsed verbatim, not just the fields this version of Coder\nunderstands.", + "type": "object", + "additionalProperties": true + }, + "id": { + "type": "integer" + }, + "uploaded_at": { + "type": "string", + "format": "date-time" + }, + "uuid": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.LogLevel": { "type": "string", "enum": [ @@ -5412,6 +6276,42 @@ const docTemplate = `{ } } }, + "codersdk.ProvisionerDaemon": { + "type": "object", + "properties": { + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "provisioners": { + "type": "array", + "items": { + "type": "string" + } + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "updated_at": { + "format": "date-time", + "allOf": [ + { + "$ref": "#/definitions/sql.NullTime" + } + ] + } + } + }, "codersdk.ProvisionerJob": { "type": "object", "properties": { @@ -5545,6 +6445,41 @@ const docTemplate = `{ } } }, + "codersdk.Replica": { + "type": "object", + "properties": { + "created_at": { + "description": "CreatedAt is the timestamp when the replica was first seen.", + "type": "string", + "format": "date-time" + }, + "database_latency": { + "description": "DatabaseLatency is the latency in microseconds to the database.", + "type": "integer" + }, + "error": { + "description": "Error is the replica error.", + "type": "string" + }, + "hostname": { + "description": "Hostname is the hostname of the replica.", + "type": "string" + }, + "id": { + "description": "ID is the unique identifier for the replica.", + "type": "string", + "format": "uuid" + }, + "region_id": { + "description": "RegionID is the region of the replica.", + "type": "integer" + }, + "relay_address": { + "description": "RelayAddress is the accessible address to relay DERP connections.", + "type": "string" + } + } + }, "codersdk.ResourceType": { "type": "string", "enum": [ @@ -5601,6 +6536,20 @@ const docTemplate = `{ } } }, + "codersdk.ServiceBannerConfig": { + "type": "object", + "properties": { + "background_color": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + }, "codersdk.SwaggerConfig": { "type": "object", "properties": { @@ -5771,6 +6720,88 @@ const docTemplate = `{ } } }, + "codersdk.TemplateRole": { + "type": "string", + "enum": [ + "admin", + "use", + "" + ], + "x-enum-varnames": [ + "TemplateRoleAdmin", + "TemplateRoleUse", + "TemplateRoleDeleted" + ] + }, + "codersdk.TemplateUser": { + "type": "object", + "required": [ + "created_at", + "email", + "id", + "username" + ], + "properties": { + "avatar_url": { + "type": "string", + "format": "uri" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "email": { + "type": "string", + "format": "email" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "last_seen_at": { + "type": "string", + "format": "date-time" + }, + "organization_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "role": { + "enum": [ + "admin", + "use" + ], + "allOf": [ + { + "$ref": "#/definitions/codersdk.TemplateRole" + } + ] + }, + "roles": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Role" + } + }, + "status": { + "enum": [ + "active", + "suspended" + ], + "allOf": [ + { + "$ref": "#/definitions/codersdk.UserStatus" + } + ] + }, + "username": { + "type": "string" + } + } + }, "codersdk.TemplateVersion": { "type": "object", "properties": { @@ -5875,6 +6906,23 @@ const docTemplate = `{ } } }, + "codersdk.UpdateTemplateACL": { + "type": "object", + "properties": { + "group_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + }, + "user_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + } + } + }, "codersdk.UpdateUserPasswordRequest": { "type": "object", "required": [ @@ -6435,6 +7483,17 @@ const docTemplate = `{ } } }, + "codersdk.WorkspaceQuota": { + "type": "object", + "properties": { + "budget": { + "type": "integer" + }, + "credits_consumed": { + "type": "integer" + } + } + }, "codersdk.WorkspaceResource": { "type": "object", "properties": { @@ -6634,6 +7693,18 @@ const docTemplate = `{ } } }, + "sql.NullTime": { + "type": "object", + "properties": { + "time": { + "type": "string" + }, + "valid": { + "description": "Valid is true if Time is not NULL", + "type": "boolean" + } + } + }, "tailcfg.DERPMap": { "type": "object", "properties": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 1e823c2ef136e..ae8733e3a44fe 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -33,6 +33,57 @@ } } }, + "/appearance": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get appearance", + "operationId": "get-appearance", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + }, + "put": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Update appearance", + "operationId": "update-appearance", + "parameters": [ + { + "description": "Update appearance request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + } + }, "/applications/auth-redirect": { "get": { "security": [ @@ -257,6 +308,27 @@ } } }, + "/entitlements": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get entitlements", + "operationId": "get-entitlements", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Entitlements" + } + } + } + } + }, "/files": { "post": { "security": [ @@ -324,6 +396,152 @@ } } }, + "/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get groups", + "operationId": "get-groups", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + } + }, + "/groups/{groupName}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get group by name", + "operationId": "get-group-by-name", + "parameters": [ + { + "type": "string", + "description": "Group name", + "name": "groupName", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "/license/{id}": { + "delete": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Delete license", + "operationId": "delete-license", + "parameters": [ + { + "type": "string", + "format": "number", + "description": "License ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + }, + "/licenses": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get licenses", + "operationId": "get-licenses", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Organizations"], + "summary": "Add new license", + "operationId": "add-new-license", + "parameters": [ + { + "description": "Add license request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AddLicenseRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, "/organizations": { "post": { "security": [ @@ -387,6 +605,78 @@ } } }, + "/organizations/{organization}/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get groups by organization", + "operationId": "get-groups-by-organization", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["Templates"], + "summary": "Create group for organization", + "operationId": "create-group-for-organization", + "parameters": [ + { + "description": "Create group request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateGroupRequest" + } + }, + { + "type": "string", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, "/organizations/{organization}/members/roles": { "get": { "security": [ @@ -506,6 +796,68 @@ } } }, + "/organizations/{organization}/provisionerdaemons": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get provisioner daemons", + "operationId": "get-provisioner-daemons", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ProvisionerDaemon" + } + } + } + } + } + }, + "/organizations/{organization}/provisionerdaemons/serve": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Serve provisioner daemon", + "operationId": "serve-provisioner-daemon", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "101": { + "description": "Switching Protocols" + } + } + } + }, "/organizations/{organization}/templates": { "get": { "security": [ @@ -902,6 +1254,128 @@ } } }, + "/replicas": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get active replicas", + "operationId": "get-active-replicas", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Replica" + } + } + } + } + } + }, + "/scim/v2/Users": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "SCIM 2.0: Create new user", + "operationId": "scim-create-new-user", + "parameters": [ + { + "description": "New user", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + } + } + }, + "/scim/v2/Users/{id}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/scim+json"], + "tags": ["Enterprise"], + "summary": "SCIM 2.0: Get user by ID", + "operationId": "scim-get-user-by-id", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "404": { + "description": "Not Found" + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/scim+json"], + "tags": ["Enterprise"], + "summary": "SCIM 2.0: Update user account", + "operationId": "scim-update-user-status", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update user request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.User" + } + } + } + } + }, "/templates/{id}": { "get": { "security": [ @@ -1155,6 +1629,78 @@ } } }, + "/templates/{template}/acl": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get template ACLs", + "operationId": "get-template-acls", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.TemplateUser" + } + } + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Update template ACL", + "operationId": "update-template-acl", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + }, + { + "description": "Update template request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateTemplateACL" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, "/templateversions/{templateversion}": { "get": { "security": [ @@ -2514,6 +3060,36 @@ } } }, + "/workspace-quota/{user}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get workspace quota by user", + "operationId": "get-workspace-quota-by-user", + "parameters": [ + { + "type": "string", + "description": "User ID, name, or me", + "name": "user", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.WorkspaceQuota" + } + } + } + } + }, "/workspaceagents/aws-instance-identity": { "post": { "security": [ @@ -3366,6 +3942,70 @@ } }, "definitions": { + "coderd.SCIMUser": { + "type": "object", + "properties": { + "active": { + "type": "boolean" + }, + "emails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "display": { + "type": "string" + }, + "primary": { + "type": "boolean" + }, + "type": { + "type": "string" + }, + "value": { + "type": "string", + "format": "email" + } + } + } + }, + "groups": { + "type": "array", + "items": {} + }, + "id": { + "type": "string" + }, + "meta": { + "type": "object", + "properties": { + "resourceType": { + "type": "string" + } + } + }, + "name": { + "type": "object", + "properties": { + "familyName": { + "type": "string" + }, + "givenName": { + "type": "string" + } + } + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + }, + "userName": { + "type": "string" + } + } + }, "coderd.cspViolation": { "type": "object", "properties": { @@ -3428,7 +4068,6 @@ "format": "date-time" }, "user_id": { - "description": "NOTE: do not ever return the HashedSecret", "type": "string", "format": "uuid" } @@ -3451,6 +4090,15 @@ } } }, + "codersdk.AddLicenseRequest": { + "type": "object", + "required": ["license"], + "properties": { + "license": { + "type": "string" + } + } + }, "codersdk.AgentGitSSHKey": { "type": "object", "properties": { @@ -3503,6 +4151,17 @@ } } }, + "codersdk.AppearanceConfig": { + "type": "object", + "properties": { + "logo_url": { + "type": "string" + }, + "service_banner": { + "$ref": "#/definitions/codersdk.ServiceBannerConfig" + } + } + }, "codersdk.AssignableRoles": { "type": "object", "properties": { @@ -3758,6 +4417,20 @@ } } }, + "codersdk.CreateGroupRequest": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "name": { + "type": "string" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.CreateOrganizationRequest": { "type": "object", "required": ["name"], @@ -4350,6 +5023,64 @@ } } }, + "codersdk.Entitlement": { + "type": "string", + "enum": ["entitled", "grace_period", "not_entitled"], + "x-enum-varnames": [ + "EntitlementEntitled", + "EntitlementGracePeriod", + "EntitlementNotEntitled" + ] + }, + "codersdk.Entitlements": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "string" + } + }, + "experimental": { + "type": "boolean" + }, + "features": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.Feature" + } + }, + "has_license": { + "type": "boolean" + }, + "trial": { + "type": "boolean" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "codersdk.Feature": { + "type": "object", + "properties": { + "actual": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "entitlement": { + "$ref": "#/definitions/codersdk.Entitlement" + }, + "limit": { + "type": "integer" + } + } + }, "codersdk.GenerateAPIKeyResponse": { "type": "object", "properties": { @@ -4445,6 +5176,34 @@ } } }, + "codersdk.Group": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.User" + } + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.Healthcheck": { "type": "object", "properties": { @@ -4462,6 +5221,27 @@ } } }, + "codersdk.License": { + "type": "object", + "properties": { + "claims": { + "description": "Claims are the JWT claims asserted by the license. Here we use\na generic string map to ensure that all data from the server is\nparsed verbatim, not just the fields this version of Coder\nunderstands.", + "type": "object", + "additionalProperties": true + }, + "id": { + "type": "integer" + }, + "uploaded_at": { + "type": "string", + "format": "date-time" + }, + "uuid": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.LogLevel": { "type": "string", "enum": ["trace", "debug", "info", "warn", "error"], @@ -4829,6 +5609,42 @@ } } }, + "codersdk.ProvisionerDaemon": { + "type": "object", + "properties": { + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "provisioners": { + "type": "array", + "items": { + "type": "string" + } + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "updated_at": { + "format": "date-time", + "allOf": [ + { + "$ref": "#/definitions/sql.NullTime" + } + ] + } + } + }, "codersdk.ProvisionerJob": { "type": "object", "properties": { @@ -4954,6 +5770,41 @@ } } }, + "codersdk.Replica": { + "type": "object", + "properties": { + "created_at": { + "description": "CreatedAt is the timestamp when the replica was first seen.", + "type": "string", + "format": "date-time" + }, + "database_latency": { + "description": "DatabaseLatency is the latency in microseconds to the database.", + "type": "integer" + }, + "error": { + "description": "Error is the replica error.", + "type": "string" + }, + "hostname": { + "description": "Hostname is the hostname of the replica.", + "type": "string" + }, + "id": { + "description": "ID is the unique identifier for the replica.", + "type": "string", + "format": "uuid" + }, + "region_id": { + "description": "RegionID is the region of the replica.", + "type": "integer" + }, + "relay_address": { + "description": "RelayAddress is the accessible address to relay DERP connections.", + "type": "string" + } + } + }, "codersdk.ResourceType": { "type": "string", "enum": [ @@ -5010,6 +5861,20 @@ } } }, + "codersdk.ServiceBannerConfig": { + "type": "object", + "properties": { + "background_color": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + }, "codersdk.SwaggerConfig": { "type": "object", "properties": { @@ -5178,6 +6043,73 @@ } } }, + "codersdk.TemplateRole": { + "type": "string", + "enum": ["admin", "use", ""], + "x-enum-varnames": [ + "TemplateRoleAdmin", + "TemplateRoleUse", + "TemplateRoleDeleted" + ] + }, + "codersdk.TemplateUser": { + "type": "object", + "required": ["created_at", "email", "id", "username"], + "properties": { + "avatar_url": { + "type": "string", + "format": "uri" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "email": { + "type": "string", + "format": "email" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "last_seen_at": { + "type": "string", + "format": "date-time" + }, + "organization_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "role": { + "enum": ["admin", "use"], + "allOf": [ + { + "$ref": "#/definitions/codersdk.TemplateRole" + } + ] + }, + "roles": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Role" + } + }, + "status": { + "enum": ["active", "suspended"], + "allOf": [ + { + "$ref": "#/definitions/codersdk.UserStatus" + } + ] + }, + "username": { + "type": "string" + } + } + }, "codersdk.TemplateVersion": { "type": "object", "properties": { @@ -5280,6 +6212,23 @@ } } }, + "codersdk.UpdateTemplateACL": { + "type": "object", + "properties": { + "group_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + }, + "user_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + } + } + }, "codersdk.UpdateUserPasswordRequest": { "type": "object", "required": ["password"], @@ -5788,6 +6737,17 @@ } } }, + "codersdk.WorkspaceQuota": { + "type": "object", + "properties": { + "budget": { + "type": "integer" + }, + "credits_consumed": { + "type": "integer" + } + } + }, "codersdk.WorkspaceResource": { "type": "object", "properties": { @@ -5968,6 +6928,18 @@ } } }, + "sql.NullTime": { + "type": "object", + "properties": { + "time": { + "type": "string" + }, + "valid": { + "description": "Valid is true if Time is not NULL", + "type": "boolean" + } + } + }, "tailcfg.DERPMap": { "type": "object", "properties": { diff --git a/codersdk/apikey.go b/codersdk/apikey.go index fd896a0d29b4a..739fe7d255a3c 100644 --- a/codersdk/apikey.go +++ b/codersdk/apikey.go @@ -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"` diff --git a/codersdk/groups.go b/codersdk/groups.go index 0647efd6e9d93..b0608f3530a3d 100644 --- a/codersdk/groups.go +++ b/codersdk/groups.go @@ -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"` diff --git a/codersdk/licenses.go b/codersdk/licenses.go index 73118de5fdb32..3ede213e53251 100644 --- a/codersdk/licenses.go +++ b/codersdk/licenses.go @@ -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 diff --git a/codersdk/provisionerdaemons.go b/codersdk/provisionerdaemons.go index da0d2b67d0910..c1b85345d0ba2 100644 --- a/codersdk/provisionerdaemons.go +++ b/codersdk/provisionerdaemons.go @@ -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"` diff --git a/codersdk/replicas.go b/codersdk/replicas.go index e74af021ee9a3..756ebcfcb756d 100644 --- a/codersdk/replicas.go +++ b/codersdk/replicas.go @@ -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"` diff --git a/codersdk/templates.go b/codersdk/templates.go index fce8b6f4c4f5c..bf00bd7e3de9a 100644 --- a/codersdk/templates.go +++ b/codersdk/templates.go @@ -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 { diff --git a/docs/api/builds.md b/docs/api/builds.md index cf904167770a6..d69028c041b17 100644 --- a/docs/api/builds.md +++ b/docs/api/builds.md @@ -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
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 | | 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
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 | | 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 diff --git a/docs/api/enterprise.md b/docs/api/enterprise.md new file mode 100644 index 0000000000000..b6df74df03153 --- /dev/null +++ b/docs/api/enterprise.md @@ -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) | + +

Response Schema

+ +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) | + +

Response Schema

+ +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) | + +

Response Schema

+ +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) | + +

Response Schema

+ +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) | + +

Response Schema

+ +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) | + +

Response Schema

+ +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). diff --git a/docs/api/organizations.md b/docs/api/organizations.md index 18d4d70192efa..825f76f8a98ce 100644 --- a/docs/api/organizations.md +++ b/docs/api/organizations.md @@ -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 diff --git a/docs/api/schemas.md b/docs/api/schemas.md index edb3d95035093..ed546daf87ca8 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -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 diff --git a/docs/api/templates.md b/docs/api/templates.md index ccab73d4cebf3..dc29086ca6e39 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -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
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 | | 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
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 | | 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
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 diff --git a/docs/api/users.md b/docs/api/users.md index 8531673ba4f3d..a01027eea638c 100644 --- a/docs/api/users.md +++ b/docs/api/users.md @@ -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 diff --git a/docs/manifest.json b/docs/manifest.json index d0b0d78417b05..f480e8f0e8226 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -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": "Builds", + "path": "./api/builds.md" }, { - "title": "Organizations", - "path": "./api/organizations.md" + "title": "Enterprise", + "path": "./api/enterprise.md" }, { - "title": "Members", - "path": "./api/members.md" + "title": "Files", + "path": "./api/files.md" }, { - "title": "Workspaces", - "path": "./api/workspaces.md" + "title": "Members", + "path": "./api/members.md" }, { - "title": "Templates", - "path": "./api/templates.md" + "title": "Organizations", + "path": "./api/organizations.md" }, { "title": "Parameters", "path": "./api/parameters.md" }, { - "title": "Users", - "path": "./api/users.md" + "title": "Schemas", + "path": "./api/schemas.md" }, { - "title": "Builds", - "path": "./api/builds.md" + "title": "Templates", + "path": "./api/templates.md" }, { - "title": "Agents", - "path": "./api/agents.md" + "title": "Users", + "path": "./api/users.md" }, { - "title": "Schemas", - "path": "./api/schemas.md" + "title": "Workspaces", + "path": "./api/workspaces.md" } ] } diff --git a/enterprise/coderd/appearance.go b/enterprise/coderd/appearance.go index ab7a9cde1b5fd..fef1c2ff5ec63 100644 --- a/enterprise/coderd/appearance.go +++ b/enterprise/coderd/appearance.go @@ -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() diff --git a/enterprise/coderd/coderd.go b/enterprise/coderd/coderd.go index 0ea4eff280357..32184e43cdac1 100644 --- a/enterprise/coderd/coderd.go +++ b/enterprise/coderd/coderd.go @@ -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() diff --git a/enterprise/coderd/groups.go b/enterprise/coderd/groups.go index ec566c8569745..ce0f92fc22339 100644 --- a/enterprise/coderd/groups.go +++ b/enterprise/coderd/groups.go @@ -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() diff --git a/enterprise/coderd/licenses.go b/enterprise/coderd/licenses.go index 28a732e2b88db..0ef3a564f9571 100644 --- a/enterprise/coderd/licenses.go +++ b/enterprise/coderd/licenses.go @@ -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) { diff --git a/enterprise/coderd/provisionerdaemons.go b/enterprise/coderd/provisionerdaemons.go index d13c4ffdd1361..d49a96ab139d6 100644 --- a/enterprise/coderd/provisionerdaemons.go +++ b/enterprise/coderd/provisionerdaemons.go @@ -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") { diff --git a/enterprise/coderd/replicas.go b/enterprise/coderd/replicas.go index 906597f257f04..b5c5af2743385 100644 --- a/enterprise/coderd/replicas.go +++ b/enterprise/coderd/replicas.go @@ -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) diff --git a/enterprise/coderd/scim.go b/enterprise/coderd/scim.go index 7ee4a41a79e60..b72486fb28ea0 100644 --- a/enterprise/coderd/scim.go +++ b/enterprise/coderd/scim.go @@ -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) { diff --git a/enterprise/coderd/scim_test.go b/enterprise/coderd/scim_test.go index 79fd0c533ad0e..c0ebf1356d120 100644 --- a/enterprise/coderd/scim_test.go +++ b/enterprise/coderd/scim_test.go @@ -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\"" }{ diff --git a/enterprise/coderd/templates.go b/enterprise/coderd/templates.go index 0e11261710f00..397101c51fb1c 100644 --- a/enterprise/coderd/templates.go +++ b/enterprise/coderd/templates.go @@ -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() diff --git a/enterprise/coderd/workspacequota.go b/enterprise/coderd/workspacequota.go index 67d07d91939ca..0416324508cb1 100644 --- a/enterprise/coderd/workspacequota.go +++ b/enterprise/coderd/workspacequota.go @@ -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) diff --git a/scripts/apidocgen/generate.sh b/scripts/apidocgen/generate.sh index b13eb2bc260d0..4ea9a490c3a1c 100755 --- a/scripts/apidocgen/generate.sh +++ b/scripts/apidocgen/generate.sh @@ -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 diff --git a/scripts/apidocgen/markdown-template/debug.def b/scripts/apidocgen/markdown-template/debug.def deleted file mode 100644 index 04fcf8f761b80..0000000000000 --- a/scripts/apidocgen/markdown-template/debug.def +++ /dev/null @@ -1 +0,0 @@ -{{= data.utils.inspect(data) }} diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index a4fa2d6b037ee..16aace697c634 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -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}}{{?}} diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index 843c676594412..117320d16e976 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -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)}}| {{~}} {{~}} {{?}} diff --git a/scripts/apidocgen/postprocess/main.go b/scripts/apidocgen/postprocess/main.go index 2b747d07d1d7a..bea72a66e47a7 100644 --- a/scripts/apidocgen/postprocess/main.go +++ b/scripts/apidocgen/postprocess/main.go @@ -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"`