Projects and assets
Routes in this group. Authentication, scope and rate limit errors apply to every route and are on the errors page.
GET/projects
List your pipeline projects, oldest first.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
limit | query | integer | No | min 1, max 100, default 50 |
cursor | query | string | No |
Request. Query: limit (1 to 100, default 50) and cursor, the nextCursor of the previous page. A key bound to one project sees only that project.
Returns. projects (id, slug, name, job, namespace, budgetCredits, creditsUsed, createdAt, updatedAt) and nextCursor, null on the last page.
Errors specific to this route. 422 invalid_cursor. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}
Read one project.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes |
Request. Path: the project slug. Needs projects:read.
Returns. id, slug, name, brief, status, metadata, budgetCredits, creditsUsed and counts of assets by status and by provenance.
Errors specific to this route. 404 project_not_found. Authentication, scope and rate limit errors apply to every route.
PUT/projects/{slug}
Create a project, or update the one with this slug.
- Scope
projects:write- Rate bucket
write, 60 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes |
Request. JSON body, ProjectPut below. name is required. The slug is 1 to 48 lowercase letters, digits or underscores and must not be reserved. A mod job (job) keeps one project; reuse its slug. budgetCredits above the non-admin ceiling needs an administrator account.
Body model ProjectPut. Unknown fields are refused.
| Field | Type | Required | Limits |
|---|---|---|---|
name | string | Yes | min length 1, max length 255 |
brief | string | No | max length 100000 |
targets | array of string or object | No | |
namespace | string | No | pattern ^[a-z0-9_.-]+$ |
extraNamespaces | array of string | No | |
license | object | No | |
style | object | No | |
hytale | object | No | |
job | string | No | |
budgetCredits | integer | No | min 0, max 100000 |
Returns. The project document plus created, true when this call made the project.
Errors specific to this route. 422 invalid_slug, 409 slug_taken, 409 job_project_exists, 409 job_project_immutable, 403 project_budget_admin_required, 422 invalid_request, 413 request_too_large. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/assets
List a project's assets with their latest delivered files.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
kind | query | string | No | |
status | query | string | No | |
offset | query | integer | No | min 0, default 0 |
limit | query | integer | No | min 1, max 2000, default 500 |
Request. Query: kind, status, offset (default 0) and limit (1 to 2000, default 500).
Returns. assets (id, projectItemId, name, status, kind, group, spec, files) and nextOffset, null when the page was not full.
Errors specific to this route. 404 project_not_found. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/assets/{assetId}
Read one asset by its manifest id.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
assetId | path | string | Yes |
Request. Path: the project slug and the asset id.
Returns. The asset object as listed above.
Errors specific to this route. 404 project_not_found, 404 asset_not_found. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/assets/{assetId}/history
Read every file version and review of one asset.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
assetId | path | string | Yes |
Request. Path: the project slug and the asset id.
Returns. asset, versions (each file version with its sha256, recipe, provenance and whether it is superseded) and reviews with their defects.
Errors specific to this route. 404 project_not_found, 404 asset_not_found. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/progress
Read the works-in-progress view of a project.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
cursor | query | string | No | max length 12, pattern ^\d+$ |
limit | query | integer | No | min 1, max 200 |
Request. Query: limit (1 to 200) and cursor page the assets. Send If-None-Match with the last ETag; an unchanged project answers 304 with no body.
Returns. Batches and each asset's live state, group and delivered icon or sounds. usage carries your plan, project budget and key caps. pollAfterSeconds says how soon to ask again and is null when nothing is queued or running. The response is private and is never cached by a shared cache.
Errors specific to this route. 404 project_not_found. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/quality
Read the rejection rate of a project's delivered files.
- Scope
projects:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
days | query | integer | No | min 1, max 90, default 7 |
Request. Query: days (1 to 90, default 7).
Returns. days, the definition used, and the counts behind the rate: unique delivered versions rejected at least once divided by delivered versions, carried files excluded.
Errors specific to this route. 404 project_not_found. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/receipt
Read the measured compute and cost totals of a project.
- Scope
results:read- Rate bucket
read, 240 a minute per key- Availability
- Answers 404 not_found where the streamlining flag is off.
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
day | query | string | No | pattern ^\d{4}-\d{2}-\d{2}$ |
Request. Query: day, a UTC date as YYYY-MM-DD, to limit the totals to one day. Needs results:read. This route answers 404 not_found where the streamlining flag is off.
Returns. Totals per batch, per cost category and per day, built from the recorded attempts. Prices that are not known are null.
Errors specific to this route. 422 invalid_day, 404 project_not_found, 404 not_found. Authentication, scope and rate limit errors apply to every route.
GET/projects/{slug}/thumbnails
Read up to 100 delivered PNG icons in one call.
- Scope
results:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
ids | query | string | Yes | min length 1, max length 4000 |
Request. Query: ids, a comma separated list of file ids (1 to 4000 characters). Needs results:read.
Returns. The icons as base64, each at most 64 KB, with the whole answer at most 2 MB. Ids that are not served come back in missing; fetch those with GET /files/{fileId}.
Errors specific to this route. 404 project_not_found. Authentication, scope and rate limit errors apply to every route.