opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-22 05:05:20 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
a9fdf87a2fb8916b4ad6ac824e6e3a3dff5e1075
coder/docs/reference/api/organizations.md
T
Nick Vigilante c84aa564ba docs: normalize code-fence languages for Shiki compatibility (#27161) 
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.

## Changes

- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags

`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).

Does not touch `offlinedocs/`.

Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)

<details>
<summary>How the fence tags were verified</summary>

Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:

```text
FAIL  env        -- Language `env` is not included in this bundle.
FAIL  Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL  promql     -- Language `promql` is not included in this bundle.
FAIL  caddyfile  -- Language `caddyfile` is not included in this bundle.
FAIL  pwsh       -- Language `pwsh` is not included in this bundle.
FAIL  output     -- Language `output` is not included in this bundle.
```

`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.

For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.

The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.

</details>


---

*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
2026-07-15 14:07:09 -04:00

22 KiB
Generated
Raw Blame History

Organizations

Get organizations

Code samples

# 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

[
  {
    "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 OK array of codersdk.Organization

Response Schema

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.

Create organization

Code samples

# 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

{
  "description": "string",
  "display_name": "string",
  "icon": "string",
  "name": "string"
}

Parameters

Name In Type Required Description
body body codersdk.CreateOrganizationRequest true Create organization request

Example responses

201 Response

{
  "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 Created codersdk.Organization

To perform this operation, you must be authenticated. Learn more.

Get organization by ID

Code samples

# 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

{
  "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 OK codersdk.Organization

To perform this operation, you must be authenticated. Learn more.

Delete organization

Code samples

# 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

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Update organization

Code samples

# 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

{
  "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 true Patch organization request

Example responses

200 Response

{
  "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 OK codersdk.Organization

To perform this operation, you must be authenticated. Learn more.

Get provisioner jobs

Code samples

# 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 object 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

[
  {
    "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 OK array of codersdk.ProvisionerJob

Response Schema

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 false
» file_id string(uuid) false
» id string(uuid) false
» initiator_id string(uuid) false
» input codersdk.ProvisionerJobInput false
»» error string false
»» template_version_id string(uuid) false
»» workspace_build_id string(uuid) false
» logs_overflowed boolean false
» metadata codersdk.ProvisionerJobMetadata 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 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 false
» tags object false
»» [any property] string false
» type codersdk.ProvisionerJobType 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.

Get provisioner job

Code samples

# 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

{
  "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 OK codersdk.ProvisionerJob

To perform this operation, you must be authenticated. Learn more.

Reference in New Issue View Git Blame Copy Permalink