Files
coder/docs/reference/api/organizations.md
T
Stefan Naglee 589e313e83 fix: emit provisioner tags query param as string in swagger (#28311)
## Summary

The `tags` query parameter on the "Get provisioner daemons" and "Get
provisioner jobs" endpoints was annotated as `@Param tags query object`,
which caused Swagger to emit `"type": "object"` for a query parameter.
Query parameters cannot be of type `object` in the OpenAPI 2.0 spec, so
this produced an invalid schema that breaks spec validators and client
generators.

As noted in the doc, the value is actually a single JSON-encoded string
(parsed via `QueryParamParser.JSONStringMap`), so the correct type is
`string`. This is a doc only concern as generators do not use this file.

## Changes

- Change the `tags` query param annotation from `object` to `string` in:
- `coderd/provisionerdaemons.go` (`GET
/api/v2/organizations/{organization}/provisionerdaemons`)
- `coderd/provisionerjobs.go` (`GET
/api/v2/organizations/{organization}/provisionerjobs`)
- Regenerate API docs (`make coderd/apidoc/.gen`):
`coderd/apidoc/swagger.json`, `coderd/apidoc/docs.go`, and the reference
markdown.

The description still documents the expected JSON form
(`{'tag1':'value1','tag2':'value2'}`), so no behavior changes for
callers.

> [!NOTE]
> This PR was generated by Coder Agents on behalf of @snagles.
2026-08-31 11:36:43 -04:00

494 lines
23 KiB
Markdown
Generated

---
# Code generated by make gen. DO NOT EDIT.
title: Organizations
---
<!-- DO NOT EDIT | GENERATED CONTENT -->
## Get organizations
### Code samples
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations`
### Example responses
> 200 Response
```json
[
{
"created_at": "2019-08-24T14:15:22Z",
"default_org_member_roles": [
"string"
],
"description": "string",
"display_name": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_default": true,
"name": "string",
"updated_at": "2019-08-24T14:15:22Z"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|-------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Organization](schemas.md#codersdkorganization) |
<h3 id="get-organizations-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
|------------------------------|-------------------|----------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `[array item]` | array | false | | |
| `» created_at` | string(date-time) | true | | |
| `» default_org_member_roles` | array | false | | Default org member roles are unioned into every member's effective roles at request time. Changes propagate to all members on the next request. |
| `» description` | string | false | | |
| `» display_name` | string | false | | |
| `» icon` | string | false | | |
| `» id` | string(uuid) | true | | |
| `» is_default` | boolean | true | | |
| `» name` | string | false | | |
| `» updated_at` | string(date-time) | true | | |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Create organization
### Code samples
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/organizations`
> Body parameter
```json
{
"description": "string",
"display_name": "string",
"icon": "string",
"name": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|------------------------------------------------------------------------------------|----------|-----------------------------|
| `body` | body | [codersdk.CreateOrganizationRequest](schemas.md#codersdkcreateorganizationrequest) | true | Create organization request |
### Example responses
> 201 Response
```json
{
"created_at": "2019-08-24T14:15:22Z",
"default_org_member_roles": [
"string"
],
"description": "string",
"display_name": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_default": true,
"name": "string",
"updated_at": "2019-08-24T14:15:22Z"
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|--------------------------------------------------------------|-------------|----------------------------------------------------------|
| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.Organization](schemas.md#codersdkorganization) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get organization by ID
### Code samples
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}`
### 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",
"default_org_member_roles": [
"string"
],
"description": "string",
"display_name": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_default": true,
"name": "string",
"updated_at": "2019-08-24T14:15:22Z"
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Organization](schemas.md#codersdkorganization) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Delete organization
### Code samples
```sh
# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/organizations/{organization} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`DELETE /api/v2/organizations/{organization}`
### Parameters
| Name | In | Type | Required | Description |
|----------------|------|--------|----------|-------------------------|
| `organization` | path | string | true | Organization ID or name |
### 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).
## Update organization
### Code samples
```sh
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /api/v2/organizations/{organization}`
> Body parameter
```json
{
"default_org_member_roles": [
"string"
],
"description": "string",
"display_name": "string",
"icon": "string",
"name": "string"
}
```
### Parameters
| Name | In | Type | Required | Description |
|----------------|------|------------------------------------------------------------------------------------|----------|----------------------------|
| `organization` | path | string | true | Organization ID or name |
| `body` | body | [codersdk.UpdateOrganizationRequest](schemas.md#codersdkupdateorganizationrequest) | true | Patch organization request |
### Example responses
> 200 Response
```json
{
"created_at": "2019-08-24T14:15:22Z",
"default_org_member_roles": [
"string"
],
"description": "string",
"display_name": "string",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_default": true,
"name": "string",
"updated_at": "2019-08-24T14:15:22Z"
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Organization](schemas.md#codersdkorganization) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get provisioner jobs
### Code samples
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerjobs \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/provisionerjobs`
### Parameters
| Name | In | Type | Required | Description |
|----------------|-------|--------------|----------|--------------------------------------------------------------------------------------|
| `organization` | path | string(uuid) | true | Organization ID |
| `limit` | query | integer | false | Page limit |
| `ids` | query | array(uuid) | false | Filter results by job IDs |
| `status` | query | string | false | Filter results by status |
| `tags` | query | string | false | Provisioner tags to filter by (JSON of the form `{'tag1':'value1','tag2':'value2'}`) |
| `initiator` | query | string(uuid) | false | Filter results by initiator |
#### Enumerated Values
| Parameter | Value(s) |
|-----------|---------------------------------------------------------------------------------|
| `status` | `canceled`, `canceling`, `failed`, `pending`, `running`, `succeeded`, `unknown` |
### Example responses
> 200 Response
```json
[
{
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"canceled_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"error": "string",
"error_code": "REQUIRED_TEMPLATE_VARIABLES",
"file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
}
]
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|-----------------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.ProvisionerJob](schemas.md#codersdkprovisionerjob) |
<h3 id="get-provisioner-jobs-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
|---------------------------------|------------------------------------------------------------------------------|----------|--------------|-------------|
| `[array item]` | array | false | | |
| `» available_workers` | array | false | | |
| `» canceled_at` | string(date-time) | false | | |
| `» completed_at` | string(date-time) | false | | |
| `» created_at` | string(date-time) | false | | |
| `» error` | string | false | | |
| `» error_code` | [codersdk.JobErrorCode](schemas.md#codersdkjoberrorcode) | false | | |
| `» file_id` | string(uuid) | false | | |
| `» id` | string(uuid) | false | | |
| `» initiator_id` | string(uuid) | false | | |
| `» input` | [codersdk.ProvisionerJobInput](schemas.md#codersdkprovisionerjobinput) | false | | |
| `»» error` | string | false | | |
| `»» template_version_id` | string(uuid) | false | | |
| `»» workspace_build_id` | string(uuid) | false | | |
| `» logs_overflowed` | boolean | false | | |
| `» metadata` | [codersdk.ProvisionerJobMetadata](schemas.md#codersdkprovisionerjobmetadata) | false | | |
| `»» template_display_name` | string | false | | |
| `»» template_icon` | string | false | | |
| `»» template_id` | string(uuid) | false | | |
| `»» template_name` | string | false | | |
| `»» template_version_name` | string | false | | |
| `»» workspace_build_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | |
| `»» workspace_id` | string(uuid) | false | | |
| `»» workspace_name` | string | false | | |
| `» organization_id` | string(uuid) | false | | |
| `» queue_position` | integer | false | | |
| `» queue_size` | integer | false | | |
| `» started_at` | string(date-time) | false | | |
| `» status` | [codersdk.ProvisionerJobStatus](schemas.md#codersdkprovisionerjobstatus) | false | | |
| `» tags` | object | false | | |
| `»» [any property]` | string | false | | |
| `» type` | [codersdk.ProvisionerJobType](schemas.md#codersdkprovisionerjobtype) | false | | |
| `» worker_id` | string(uuid) | false | | |
| `» worker_name` | string | false | | |
#### Enumerated Values
| Property | Value(s) |
|------------------------------|--------------------------------------------------------------------------|
| `error_code` | `INSUFFICIENT_QUOTA`, `REQUIRED_TEMPLATE_VARIABLES` |
| `workspace_build_transition` | `delete`, `start`, `stop` |
| `status` | `canceled`, `canceling`, `failed`, `pending`, `running`, `succeeded` |
| `type` | `template_version_dry_run`, `template_version_import`, `workspace_build` |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get provisioner job
### Code samples
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerjobs/{job} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/organizations/{organization}/provisionerjobs/{job}`
### Parameters
| Name | In | Type | Required | Description |
|----------------|------|--------------|----------|-----------------|
| `organization` | path | string(uuid) | true | Organization ID |
| `job` | path | string(uuid) | true | Job ID |
### Example responses
> 200 Response
```json
{
"available_workers": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"canceled_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"error": "string",
"error_code": "REQUIRED_TEMPLATE_VARIABLES",
"file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
"input": {
"error": "string",
"template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
"workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
},
"logs_overflowed": true,
"metadata": {
"template_display_name": "string",
"template_icon": "string",
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"template_name": "string",
"template_version_name": "string",
"workspace_build_transition": "start",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"workspace_name": "string"
},
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"queue_position": 0,
"queue_size": 0,
"started_at": "2019-08-24T14:15:22Z",
"status": "pending",
"tags": {
"property1": "string",
"property2": "string"
},
"type": "template_version_import",
"worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b",
"worker_name": "string"
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|--------------------------------------------------------------|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ProvisionerJob](schemas.md#codersdkprovisionerjob) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).