Builds

REST endpoints for builds. Bearer-auth required.

GET /api/builds

List builds.

Query parameters

• limit (optional): Page size (1–100, default 100).
• after (optional): Keyset cursor — return the page after this row (next page).
• before (optional): Keyset cursor — return the page before this row (prev page).
• ids (optional): Comma-separated list of IDs. Narrows results to these IDs within the caller's accessible scope (does not bypass access checks).
• filter (optional): Nested filter expression (<Entity>Filter): AND/OR/NOT + per-field comparison operators + relation traversal. JSON-encoded on the query string.
• orderBy (optional): Multi-key sort (<Entity>OrderBy[]): array of { field: direction } applied in order. Directions: asc/desc plus the four explicit nulls variants. JSON-encoded on the query string.
• workspace_id (optional): Filter builds to this workspace.
• entity_id (optional): Filter to builds for a specific entity (app, function, …).
• app_id (optional): Filter builds to this app.
• status (optional): Filter by build status.
• trigger (optional): Shorthand: filter where trigger equals this value.
• created_by (optional): Shorthand: filter where createdBy equals this value.

Response

{
  "data": [
    {
      "id": "<...>",
      "workspaceId": "<...>",
      "entityId": "<...>",
      "sequenceNumber": "<...>",
      "status": "<...>",
      "trigger": "<...>",
      "sourceEventId": "<...>",
      "error": "<...>",
      "metadata": "<...>",
      "createdBy": "<...>",
      "startedAt": "<...>",
      "completedAt": "<...>",
      "createdAt": "<...>"
    }
  ],
  "pageInfo": {
    "total": "number",
    "hasNextPage": "boolean",
    "hasPreviousPage": "boolean",
    "startCursor": "string",
    "endCursor": "string"
  }
}

POST /api/builds

Create build

Trigger a build for a specific app version. Returns the freshly-created build row so the caller can poll status via GET /api/builds/{id}.

Request body

{
  "appVersionId": "string"
}

Response

{
  "id": "string",
  "workspaceId": "string",
  "entityId": "string",
  "sequenceNumber": "integer",
  "status": "pending | running | completed | failed",
  "trigger": "manual | auto | redeploy",
  "sourceEventId": "string",
  "error": "string",
  "metadata": {},
  "createdBy": "string",
  "startedAt": "string",
  "completedAt": "string",
  "createdAt": "string"
}

GET /api/builds/{id}

Get a build by ID, including its step list.

Path parameters

• id (required): Build to retrieve.

Response

{
  "id": "string",
  "workspaceId": "string",
  "entityId": "string",
  "sequenceNumber": "integer",
  "status": "pending | running | completed | failed",
  "trigger": "manual | auto | redeploy",
  "sourceEventId": "string",
  "error": "string",
  "metadata": {},
  "createdBy": "string",
  "startedAt": "string",
  "completedAt": "string",
  "createdAt": "string",
  "steps": ["<...>"]
}

POST /api/builds/{id}/cancel

Cancel build

Cancel a pending or running build. In-flight container operations cannot be aborted but results will be discarded.

Path parameters

• id (required): The build's prefixed ID (e.g. bld_...).

Request body

{
  "reason?": "string"
}

Response

{
  "success": "boolean"
}