synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f2983164f550be7bb4fa2bc8b0536e446913111d
coder/docs/reference/api/organizations.md
Susana Ferreira f044cc3550 feat: add provisioner daemon name to provisioner jobs responses (#17877) 
# Description

This PR adds the `worker_name` field to the provisioner jobs endpoint.

To achieve this, the following SQL query was updated:
-
`GetProvisionerJobsByOrganizationAndStatusWithQueuePositionAndProvisioner`

As a result, the `codersdk.ProvisionerJob` type, which represents the
provisioner job API response, was modified to include the new field.

**Notes:** 
* As mentioned in
[comment](https://github.com/coder/coder/pull/17877#discussion_r2093218206),
the `GetProvisionerJobsByIDsWithQueuePosition` query was not changed due
to load concerns. This means that for template and template version
endpoints, `worker_id` will still be returned, but `worker_name` will
not.
* Similar to `worker_id`, the `worker_name` is only present once a job
is assigned to a provisioner daemon. For jobs in a pending state (not
yet assigned), neither `worker_id` nor `worker_name` will be returned.

---

# Affected Endpoints

- `/organizations/{organization}/provisionerjobs`
- `/organizations/{organization}/provisionerjobs/{job}`

---

# Testing

- Added new tests verifying that both `worker_id` and `worker_name` are
returned once a provisioner job reaches the **succeeded** state.
- Existing tests covering state transitions and other logic remain
unchanged, as they test different scenarios.

---

# Front-end Changes

Admin provisioner jobs dashboard:
<img width="1088" alt="Screenshot 2025-05-16 at 11 51 33"
src="https://github.com/user-attachments/assets/0e20e360-c615-4497-84b7-693777c5443e"
/>

Fixes: https://github.com/coder/coder/issues/16982
2025-05-19 16:05:39 +01:00

22 KiB
Generated
Raw Blame History

Organizations

Add new license

Code samples

# 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

{
  "license": "string"
}

Parameters

Name In Type Required Description
body body codersdk.AddLicenseRequest true Add license request

Example responses

201 Response

{
  "claims": {},
  "id": 0,
  "uploaded_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.License

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

Update license entitlements

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/licenses/refresh-entitlements \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /licenses/refresh-entitlements

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Created codersdk.Response

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

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 /organizations

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "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
» 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 /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",
  "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 /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",
  "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 /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 /organizations/{organization}

Body parameter

{
  "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",
  "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 /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'})

Enumerated Values

Parameter Value
status pending
status running
status succeeded
status canceling
status canceled
status failed
status unknown
status pending
status running
status succeeded
status canceling
status canceled
status failed

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",
    "input": {
      "error": "string",
      "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
      "workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
    },
    "metadata": {
      "template_display_name": "string",
      "template_icon": "string",
      "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
      "template_name": "string",
      "template_version_name": "string",
      "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
» input codersdk.ProvisionerJobInput false
»» error string false
»» template_version_id string(uuid) false
»» workspace_build_id string(uuid) 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_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
error_code REQUIRED_TEMPLATE_VARIABLES
status pending
status running
status succeeded
status canceling
status canceled
status failed
type template_version_import
type workspace_build
type template_version_dry_run

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 /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",
  "input": {
    "error": "string",
    "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
    "workspace_build_id": "badaf2eb-96c5-4050-9f1d-db2d39ca5478"
  },
  "metadata": {
    "template_display_name": "string",
    "template_icon": "string",
    "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
    "template_name": "string",
    "template_version_name": "string",
    "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.