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
bbb0fab1de45fda4724f7d9a84508ac098dce5b0
coder/docs/api/builds.md
T
Mathias Fredriksson 8dac0356ed refactor: replace startup script logs EOF with starting/ready time (#8082) 
This commit reverts some of the changes in #8029 and implements an
alternative method of keeping track of when the startup script has ended
and there will be no more logs.

This is achieved by adding new agent fields for tracking when the agent
enters the "starting" and "ready"/"start_error" lifecycle states. The
timestamps simplify logic since we don't need understand if the current
state is before or after the state we're interested in. They can also be
used to show data like how long the startup script took to execute. This
also allowed us to remove the EOF field from the logs as the
implementation was problematic when we returned the EOF log entry in the
response since requesting _after_ that ID would give no logs and the API
would thus lose track of EOF.
2023-06-20 14:41:55 +03:00

108 KiB
Raw Blame History

Builds

Get workspace build by user, workspace name, and build number

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacename}/builds/{buildnumber} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /users/{user}/workspace/{workspacename}/builds/{buildnumber}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
workspacename path string true Workspace name
buildnumber path string(number) true Build number

Example responses

200 Response

{
  "build_number": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "daily_cost": 0,
  "deadline": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
  "initiator_name": "string",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "max_deadline": "2019-08-24T14:15:22Z",
  "reason": "initiator",
  "resources": [
    {
      "agents": [
        {
          "apps": [
            {
              "command": "string",
              "display_name": "string",
              "external": true,
              "health": "disabled",
              "healthcheck": {
                "interval": 0,
                "threshold": 0,
                "url": "string"
              },
              "icon": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "sharing_level": "owner",
              "slug": "string",
              "subdomain": true,
              "url": "string"
            }
          ],
          "architecture": "string",
          "connection_timeout_seconds": 0,
          "created_at": "2019-08-24T14:15:22Z",
          "directory": "string",
          "disconnected_at": "2019-08-24T14:15:22Z",
          "environment_variables": {
            "property1": "string",
            "property2": "string"
          },
          "expanded_directory": "string",
          "first_connected_at": "2019-08-24T14:15:22Z",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "instance_id": "string",
          "last_connected_at": "2019-08-24T14:15:22Z",
          "latency": {
            "property1": {
              "latency_ms": 0,
              "preferred": true
            },
            "property2": {
              "latency_ms": 0,
              "preferred": true
            }
          },
          "lifecycle_state": "created",
          "login_before_ready": true,
          "name": "string",
          "operating_system": "string",
          "ready_at": "2019-08-24T14:15:22Z",
          "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
          "shutdown_script": "string",
          "shutdown_script_timeout_seconds": 0,
          "started_at": "2019-08-24T14:15:22Z",
          "startup_logs_length": 0,
          "startup_logs_overflowed": true,
          "startup_script": "string",
          "startup_script_behavior": "blocking",
          "startup_script_timeout_seconds": 0,
          "status": "connecting",
          "subsystem": "envbox",
          "troubleshooting_url": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "version": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "daily_cost": 0,
      "hide": true,
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
      "metadata": [
        {
          "key": "string",
          "sensitive": true,
          "value": "string"
        }
      ],
      "name": "string",
      "type": "string",
      "workspace_transition": "start"
    }
  ],
  "status": "pending",
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
  "template_version_name": "string",
  "transition": "start",
  "updated_at": "2019-08-24T14:15:22Z",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "workspace_name": "string",
  "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
  "workspace_owner_name": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceBuild

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

Get workspace build

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspacebuilds/{workspacebuild}

Parameters

Name In Type Required Description
workspacebuild path string true Workspace build ID

Example responses

200 Response

{
  "build_number": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "daily_cost": 0,
  "deadline": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
  "initiator_name": "string",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "max_deadline": "2019-08-24T14:15:22Z",
  "reason": "initiator",
  "resources": [
    {
      "agents": [
        {
          "apps": [
            {
              "command": "string",
              "display_name": "string",
              "external": true,
              "health": "disabled",
              "healthcheck": {
                "interval": 0,
                "threshold": 0,
                "url": "string"
              },
              "icon": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "sharing_level": "owner",
              "slug": "string",
              "subdomain": true,
              "url": "string"
            }
          ],
          "architecture": "string",
          "connection_timeout_seconds": 0,
          "created_at": "2019-08-24T14:15:22Z",
          "directory": "string",
          "disconnected_at": "2019-08-24T14:15:22Z",
          "environment_variables": {
            "property1": "string",
            "property2": "string"
          },
          "expanded_directory": "string",
          "first_connected_at": "2019-08-24T14:15:22Z",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "instance_id": "string",
          "last_connected_at": "2019-08-24T14:15:22Z",
          "latency": {
            "property1": {
              "latency_ms": 0,
              "preferred": true
            },
            "property2": {
              "latency_ms": 0,
              "preferred": true
            }
          },
          "lifecycle_state": "created",
          "login_before_ready": true,
          "name": "string",
          "operating_system": "string",
          "ready_at": "2019-08-24T14:15:22Z",
          "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
          "shutdown_script": "string",
          "shutdown_script_timeout_seconds": 0,
          "started_at": "2019-08-24T14:15:22Z",
          "startup_logs_length": 0,
          "startup_logs_overflowed": true,
          "startup_script": "string",
          "startup_script_behavior": "blocking",
          "startup_script_timeout_seconds": 0,
          "status": "connecting",
          "subsystem": "envbox",
          "troubleshooting_url": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "version": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "daily_cost": 0,
      "hide": true,
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
      "metadata": [
        {
          "key": "string",
          "sensitive": true,
          "value": "string"
        }
      ],
      "name": "string",
      "type": "string",
      "workspace_transition": "start"
    }
  ],
  "status": "pending",
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
  "template_version_name": "string",
  "transition": "start",
  "updated_at": "2019-08-24T14:15:22Z",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "workspace_name": "string",
  "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
  "workspace_owner_name": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceBuild

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

Cancel workspace build

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/cancel \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /workspacebuilds/{workspacebuild}/cancel

Parameters

Name In Type Required Description
workspacebuild path string true Workspace build ID

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.

Get workspace build logs

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/logs \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspacebuilds/{workspacebuild}/logs

Parameters

Name In Type Required Description
workspacebuild path string true Workspace build ID
before query integer false Before Unix timestamp
after query integer false After Unix timestamp
follow query boolean false Follow log stream

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": 0,
    "log_level": "trace",
    "log_source": "provisioner_daemon",
    "output": "string",
    "stage": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.ProvisionerJobLog

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false
» id integer false
» log_level codersdk.LogLevel false
» log_source codersdk.LogSource false
» output string false
» stage string false

Enumerated Values

Property Value
log_level trace
log_level debug
log_level info
log_level warn
log_level error
log_source provisioner_daemon
log_source provisioner

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

Get build parameters for workspace build

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/parameters \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspacebuilds/{workspacebuild}/parameters

Parameters

Name In Type Required Description
workspacebuild path string true Workspace build ID

Example responses

200 Response

[
  {
    "name": "string",
    "value": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.WorkspaceBuildParameter

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» name string false
» value string false

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

Get workspace resources for workspace build

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/resources \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspacebuilds/{workspacebuild}/resources

Parameters

Name In Type Required Description
workspacebuild path string true Workspace build ID

Example responses

200 Response

[
  {
    "agents": [
      {
        "apps": [
          {
            "command": "string",
            "display_name": "string",
            "external": true,
            "health": "disabled",
            "healthcheck": {
              "interval": 0,
              "threshold": 0,
              "url": "string"
            },
            "icon": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "sharing_level": "owner",
            "slug": "string",
            "subdomain": true,
            "url": "string"
          }
        ],
        "architecture": "string",
        "connection_timeout_seconds": 0,
        "created_at": "2019-08-24T14:15:22Z",
        "directory": "string",
        "disconnected_at": "2019-08-24T14:15:22Z",
        "environment_variables": {
          "property1": "string",
          "property2": "string"
        },
        "expanded_directory": "string",
        "first_connected_at": "2019-08-24T14:15:22Z",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "instance_id": "string",
        "last_connected_at": "2019-08-24T14:15:22Z",
        "latency": {
          "property1": {
            "latency_ms": 0,
            "preferred": true
          },
          "property2": {
            "latency_ms": 0,
            "preferred": true
          }
        },
        "lifecycle_state": "created",
        "login_before_ready": true,
        "name": "string",
        "operating_system": "string",
        "ready_at": "2019-08-24T14:15:22Z",
        "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
        "shutdown_script": "string",
        "shutdown_script_timeout_seconds": 0,
        "started_at": "2019-08-24T14:15:22Z",
        "startup_logs_length": 0,
        "startup_logs_overflowed": true,
        "startup_script": "string",
        "startup_script_behavior": "blocking",
        "startup_script_timeout_seconds": 0,
        "status": "connecting",
        "subsystem": "envbox",
        "troubleshooting_url": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "version": "string"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "daily_cost": 0,
    "hide": true,
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
    "metadata": [
      {
        "key": "string",
        "sensitive": true,
        "value": "string"
      }
    ],
    "name": "string",
    "type": "string",
    "workspace_transition": "start"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.WorkspaceResource

Response Schema

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 »»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 false
»»» healthcheck codersdk.Healthcheck 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 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
»» expanded_directory 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 false
»»»» latency_ms number false
»»»» preferred boolean false
»» lifecycle_state codersdk.WorkspaceAgentLifecycle false
»» login_before_ready boolean false Deprecated: Use StartupScriptBehavior instead.
»» name string false
»» operating_system string false
»» ready_at string(date-time) false
»» resource_id string(uuid) false
»» shutdown_script string false
»» shutdown_script_timeout_seconds integer false
»» started_at string(date-time) false
»» startup_logs_length integer false
»» startup_logs_overflowed boolean false
»» startup_script string false
»» startup_script_behavior codersdk.WorkspaceAgentStartupScriptBehavior false
»» startup_script_timeout_seconds integer false »startup script timeout seconds is the number of seconds to wait for the startup script to complete. If the script does not complete within this time, the agent lifecycle will be marked as start_timeout.
»» status codersdk.WorkspaceAgentStatus false
»» subsystem codersdk.AgentSubsystem 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 false

Enumerated Values

Property Value
health disabled
health initializing
health healthy
health unhealthy
sharing_level owner
sharing_level authenticated
sharing_level public
lifecycle_state created
lifecycle_state starting
lifecycle_state start_timeout
lifecycle_state start_error
lifecycle_state ready
lifecycle_state shutting_down
lifecycle_state shutdown_timeout
lifecycle_state shutdown_error
lifecycle_state off
startup_script_behavior blocking
startup_script_behavior non-blocking
status connecting
status connected
status disconnected
status timeout
subsystem envbox
workspace_transition start
workspace_transition stop
workspace_transition delete

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

Get provisioner state for workspace build

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/state \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspacebuilds/{workspacebuild}/state

Parameters

Name In Type Required Description
workspacebuild path string true Workspace build ID

Example responses

200 Response

{
  "build_number": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "daily_cost": 0,
  "deadline": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
  "initiator_name": "string",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "max_deadline": "2019-08-24T14:15:22Z",
  "reason": "initiator",
  "resources": [
    {
      "agents": [
        {
          "apps": [
            {
              "command": "string",
              "display_name": "string",
              "external": true,
              "health": "disabled",
              "healthcheck": {
                "interval": 0,
                "threshold": 0,
                "url": "string"
              },
              "icon": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "sharing_level": "owner",
              "slug": "string",
              "subdomain": true,
              "url": "string"
            }
          ],
          "architecture": "string",
          "connection_timeout_seconds": 0,
          "created_at": "2019-08-24T14:15:22Z",
          "directory": "string",
          "disconnected_at": "2019-08-24T14:15:22Z",
          "environment_variables": {
            "property1": "string",
            "property2": "string"
          },
          "expanded_directory": "string",
          "first_connected_at": "2019-08-24T14:15:22Z",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "instance_id": "string",
          "last_connected_at": "2019-08-24T14:15:22Z",
          "latency": {
            "property1": {
              "latency_ms": 0,
              "preferred": true
            },
            "property2": {
              "latency_ms": 0,
              "preferred": true
            }
          },
          "lifecycle_state": "created",
          "login_before_ready": true,
          "name": "string",
          "operating_system": "string",
          "ready_at": "2019-08-24T14:15:22Z",
          "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
          "shutdown_script": "string",
          "shutdown_script_timeout_seconds": 0,
          "started_at": "2019-08-24T14:15:22Z",
          "startup_logs_length": 0,
          "startup_logs_overflowed": true,
          "startup_script": "string",
          "startup_script_behavior": "blocking",
          "startup_script_timeout_seconds": 0,
          "status": "connecting",
          "subsystem": "envbox",
          "troubleshooting_url": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "version": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "daily_cost": 0,
      "hide": true,
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
      "metadata": [
        {
          "key": "string",
          "sensitive": true,
          "value": "string"
        }
      ],
      "name": "string",
      "type": "string",
      "workspace_transition": "start"
    }
  ],
  "status": "pending",
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
  "template_version_name": "string",
  "transition": "start",
  "updated_at": "2019-08-24T14:15:22Z",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "workspace_name": "string",
  "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
  "workspace_owner_name": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceBuild

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

Get workspace builds by workspace ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{workspace}/builds \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaces/{workspace}/builds

Parameters

Name In Type Required Description
workspace path string(uuid) true Workspace ID
after_id query string(uuid) false After ID
limit query integer false Page limit
offset query integer false Page offset
since query string(date-time) false Since timestamp

Example responses

200 Response

[
  {
    "build_number": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "daily_cost": 0,
    "deadline": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
    "initiator_name": "string",
    "job": {
      "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": "MISSING_TEMPLATE_PARAMETER",
      "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "started_at": "2019-08-24T14:15:22Z",
      "status": "pending",
      "tags": {
        "property1": "string",
        "property2": "string"
      },
      "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
    },
    "max_deadline": "2019-08-24T14:15:22Z",
    "reason": "initiator",
    "resources": [
      {
        "agents": [
          {
            "apps": [
              {
                "command": "string",
                "display_name": "string",
                "external": true,
                "health": "disabled",
                "healthcheck": {
                  "interval": 0,
                  "threshold": 0,
                  "url": "string"
                },
                "icon": "string",
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                "sharing_level": "owner",
                "slug": "string",
                "subdomain": true,
                "url": "string"
              }
            ],
            "architecture": "string",
            "connection_timeout_seconds": 0,
            "created_at": "2019-08-24T14:15:22Z",
            "directory": "string",
            "disconnected_at": "2019-08-24T14:15:22Z",
            "environment_variables": {
              "property1": "string",
              "property2": "string"
            },
            "expanded_directory": "string",
            "first_connected_at": "2019-08-24T14:15:22Z",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "instance_id": "string",
            "last_connected_at": "2019-08-24T14:15:22Z",
            "latency": {
              "property1": {
                "latency_ms": 0,
                "preferred": true
              },
              "property2": {
                "latency_ms": 0,
                "preferred": true
              }
            },
            "lifecycle_state": "created",
            "login_before_ready": true,
            "name": "string",
            "operating_system": "string",
            "ready_at": "2019-08-24T14:15:22Z",
            "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
            "shutdown_script": "string",
            "shutdown_script_timeout_seconds": 0,
            "started_at": "2019-08-24T14:15:22Z",
            "startup_logs_length": 0,
            "startup_logs_overflowed": true,
            "startup_script": "string",
            "startup_script_behavior": "blocking",
            "startup_script_timeout_seconds": 0,
            "status": "connecting",
            "subsystem": "envbox",
            "troubleshooting_url": "string",
            "updated_at": "2019-08-24T14:15:22Z",
            "version": "string"
          }
        ],
        "created_at": "2019-08-24T14:15:22Z",
        "daily_cost": 0,
        "hide": true,
        "icon": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
        "metadata": [
          {
            "key": "string",
            "sensitive": true,
            "value": "string"
          }
        ],
        "name": "string",
        "type": "string",
        "workspace_transition": "start"
      }
    ],
    "status": "pending",
    "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
    "template_version_name": "string",
    "transition": "start",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
    "workspace_name": "string",
    "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
    "workspace_owner_name": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.WorkspaceBuild

Response Schema

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 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
»» started_at string(date-time) false
»» status codersdk.ProvisionerJobStatus false
»» tags object false
»»» [any property] string false
»» worker_id string(uuid) false
» max_deadline string(date-time) false
» reason codersdk.BuildReason 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 false
»»»» healthcheck codersdk.Healthcheck 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 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
»»» expanded_directory 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 false
»»»»» latency_ms number false
»»»»» preferred boolean false
»»» lifecycle_state codersdk.WorkspaceAgentLifecycle false
»»» login_before_ready boolean false Deprecated: Use StartupScriptBehavior instead.
»»» name string false
»»» operating_system string false
»»» ready_at string(date-time) false
»»» resource_id string(uuid) false
»»» shutdown_script string false
»»» shutdown_script_timeout_seconds integer false
»»» started_at string(date-time) false
»»» startup_logs_length integer false
»»» startup_logs_overflowed boolean false
»»» startup_script string false
»»» startup_script_behavior codersdk.WorkspaceAgentStartupScriptBehavior false
»»» startup_script_timeout_seconds integer false »»startup script timeout seconds is the number of seconds to wait for the startup script to complete. If the script does not complete within this time, the agent lifecycle will be marked as start_timeout.
»»» status codersdk.WorkspaceAgentStatus false
»»» subsystem codersdk.AgentSubsystem 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 false
» status codersdk.WorkspaceStatus false
» template_version_id string(uuid) false
» template_version_name string false
» transition codersdk.WorkspaceTransition 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

Property Value
error_code MISSING_TEMPLATE_PARAMETER
error_code REQUIRED_TEMPLATE_VARIABLES
status pending
status running
status succeeded
status canceling
status canceled
status failed
reason initiator
reason autostart
reason autostop
health disabled
health initializing
health healthy
health unhealthy
sharing_level owner
sharing_level authenticated
sharing_level public
lifecycle_state created
lifecycle_state starting
lifecycle_state start_timeout
lifecycle_state start_error
lifecycle_state ready
lifecycle_state shutting_down
lifecycle_state shutdown_timeout
lifecycle_state shutdown_error
lifecycle_state off
startup_script_behavior blocking
startup_script_behavior non-blocking
status connecting
status connected
status disconnected
status timeout
subsystem envbox
workspace_transition start
workspace_transition stop
workspace_transition delete
status pending
status starting
status running
status stopping
status stopped
status failed
status canceling
status canceled
status deleting
status deleted
transition start
transition stop
transition delete

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

Create workspace build

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaces/{workspace}/builds \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaces/{workspace}/builds

Body parameter

{
  "dry_run": true,
  "log_level": "debug",
  "orphan": true,
  "rich_parameter_values": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "state": [0],
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
  "transition": "create"
}

Parameters

Name In Type Required Description
workspace path string(uuid) true Workspace ID
body body codersdk.CreateWorkspaceBuildRequest true Create workspace build request

Example responses

200 Response

{
  "build_number": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "daily_cost": 0,
  "deadline": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3",
  "initiator_name": "string",
  "job": {
    "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": "MISSING_TEMPLATE_PARAMETER",
    "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "pending",
    "tags": {
      "property1": "string",
      "property2": "string"
    },
    "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b"
  },
  "max_deadline": "2019-08-24T14:15:22Z",
  "reason": "initiator",
  "resources": [
    {
      "agents": [
        {
          "apps": [
            {
              "command": "string",
              "display_name": "string",
              "external": true,
              "health": "disabled",
              "healthcheck": {
                "interval": 0,
                "threshold": 0,
                "url": "string"
              },
              "icon": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "sharing_level": "owner",
              "slug": "string",
              "subdomain": true,
              "url": "string"
            }
          ],
          "architecture": "string",
          "connection_timeout_seconds": 0,
          "created_at": "2019-08-24T14:15:22Z",
          "directory": "string",
          "disconnected_at": "2019-08-24T14:15:22Z",
          "environment_variables": {
            "property1": "string",
            "property2": "string"
          },
          "expanded_directory": "string",
          "first_connected_at": "2019-08-24T14:15:22Z",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "instance_id": "string",
          "last_connected_at": "2019-08-24T14:15:22Z",
          "latency": {
            "property1": {
              "latency_ms": 0,
              "preferred": true
            },
            "property2": {
              "latency_ms": 0,
              "preferred": true
            }
          },
          "lifecycle_state": "created",
          "login_before_ready": true,
          "name": "string",
          "operating_system": "string",
          "ready_at": "2019-08-24T14:15:22Z",
          "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
          "shutdown_script": "string",
          "shutdown_script_timeout_seconds": 0,
          "started_at": "2019-08-24T14:15:22Z",
          "startup_logs_length": 0,
          "startup_logs_overflowed": true,
          "startup_script": "string",
          "startup_script_behavior": "blocking",
          "startup_script_timeout_seconds": 0,
          "status": "connecting",
          "subsystem": "envbox",
          "troubleshooting_url": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "version": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "daily_cost": 0,
      "hide": true,
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
      "metadata": [
        {
          "key": "string",
          "sensitive": true,
          "value": "string"
        }
      ],
      "name": "string",
      "type": "string",
      "workspace_transition": "start"
    }
  ],
  "status": "pending",
  "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1",
  "template_version_name": "string",
  "transition": "start",
  "updated_at": "2019-08-24T14:15:22Z",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "workspace_name": "string",
  "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
  "workspace_owner_name": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceBuild

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

Reference in New Issue View Git Blame Copy Permalink