projects

Project lifecycle within a tenant.

Amfelt REST API · v1.13.0 · https://api.amfelt.com

GET `/v1/table-types`

List the table-type taxonomy.

Returns each table-type classification and the history mode it derives when no explicit historyMode is set (ADR-068). Static reference data: core owns the taxonomy and the derivation, and the UI renders this list rather than keeping a second copy that could drift.

Responses

200 The table-type taxonomy, in canonical presentation order.

application/json

Property	Type	Required	Description
`data`	TableType []	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects`

List projects.

Returns the projects belonging to the caller’s active tenant.

Parameters

Name	In	Required	Type	Description
`archived`	query	No	boolean	When true, returns archived (disabled) projects instead of active ones.
When true, returns archived (disabled) projects instead of active ones.

Responses

200 The tenant's projects.

application/json

Property	Type	Required	Description
`data`	Project []	Yes	The projects.
The projects.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects`

Create a project.

Creates a project in the caller’s active tenant.

Request body (required)

application/json

Property	Type	Required	Description
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`environments`	string[]	No	Initial DTAP environment slugs to bind (defaults to [“development”] when omitted).
Initial DTAP environment slugs to bind (defaults to [“development”] when omitted).
`time_zone`	string	No	The project’s IANA time zone name. The app sends the creating user’s browser time zone. Omitted, the project gets “UTC”. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. The app sends the creating user’s browser time zone. Omitted, the project gets “UTC”. Examples: `Europe/Amsterdam`.

Responses

201 The project was created.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

400 Code invalid_argument: the request was malformed or failed validation. A time_zone that is not an IANA time zone name answers with field=time_zone. Nothing is created.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/environments`

List DTAP environments.

The DTAP environment lookup, ordered by promotion order.

Responses

200 The environments.

application/json

Property	Type	Required	Description
`data`	Environment []	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/unarchive`

Re-enable a disabled project.

Restores a previously archived (disabled) project to active status.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

200 The restored project.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/sources`

List a project's data sources.

Returns all configured data-source connections for the project in the requested environment (non-secret view).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`env`	query	No	string	DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.
DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.

Responses

200 The project's data sources.

application/json

Property	Type	Required	Description
`data`	ProjectSource []	Yes	The data sources.
The data sources.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/sources`

Create a data source for a project.

Registers a new data-source connection (vault-first) in the requested environment. Secret fields are write-only.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`env`	query	No	string	DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.
DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.

Request body (required)

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`config`	object	No	Non-secret connection fields (host, port, database, schema).
Non-secret connection fields (host, port, database, schema).
`secret`	object	No	Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.

Responses

201 The data source was created.

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`auto_discover`		No	The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`first_job`		No	The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
`id`	string	Yes	Data source identifier.
Data source identifier.
`last_test`	LastConnectionTest	No

`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.
`updated_at`	string	Yes	When the data source’s configuration last changed. Recording a connection test does not move it.
When the data source’s configuration last changed. Recording a connection test does not move it.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/schedules`

List the schedule state of a project's jobs.

Returns one entry per scheduled entry of the project’s jobs in the given environment, keyed by job_name and run_name. This is control-plane runtime state maintained by the scheduler; it is not part of the job document and is never written back to it. A job entry that carries no cron expression runs on demand only and has no entry here, so an absent entry and a null next_run_at mean different things.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The schedule state of the project's jobs in the given environment.

application/json

Property	Type	Required	Description
`data`	ScheduleState []	Yes	One entry per scheduled entry across the project’s jobs. A job with no scheduled entries contributes nothing.
One entry per scheduled entry across the project’s jobs. A job with no scheduled entries contributes nothing.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/runs`

Trigger a run of one named job of a project from the control plane.

Dispatches a cmd.execute_flow command to the project’s assigned agent, which executes the job named by job_name. A body with the deprecated source_slug only runs the source’s one job. Returns a correlation reference that can be used to cancel the run.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Request body (required)

application/json

Property	Type	Required	Description
`dry_run`	boolean	No	When true the run executes in dry-run mode (no data written).
When true the run executes in dry-run mode (no data written).
`environment_id`	string	Yes	DTAP environment slug (e.g. production). Examples: `production`.
DTAP environment slug (e.g. production). Examples: `production`.
`job_name`	string	No	Name of the job to run, unique within the environment. Send it on every new request. The api rejects a body with neither job_name nor source_slug with HTTP 400. Examples: `sales_daily`.
Name of the job to run, unique within the environment. Send it on every new request. The api rejects a body with neither job_name nor source_slug with HTTP 400. Examples: `sales_daily`.
`source_slug`	string	No	Deprecated: send job_name. Catalog source slug, accepted only as a fallback for older clients: when the source has exactly one job, that job runs; when it has more than one, the request fails with HTTP 409. When sent with job_name, it must name the job’s source, or the request fails with HTTP 400. A body with neither job_name nor source_slug fails with HTTP 400.
Deprecated: send job_name. Catalog source slug, accepted only as a fallback for older clients: when the source has exactly one job, that job runs; when it has more than one, the request fails with HTTP 409. When sent with job_name, it must name the job’s source, or the request fails with HTTP 400. A body with neither job_name nor source_slug fails with HTTP 400.
`strategy`	string	No	Load strategy for this run only; the job does not change. absent = the strategy of the job’s first run entry (full when the job has no run entry); `cdc` is not accepted. Valid values are: `full`, `incremental`. Examples: `full`.
Load strategy for this run only; the job does not change. absent = the strategy of the job’s first run entry (full when the job has no run entry); `cdc` is not accepted. Valid values are: `full`, `incremental`. Examples: `full`.

Responses

202 Run dispatched to the project's assigned agent.

application/json

Property	Type	Required	Description
`cmd_id`	string	Yes	Correlation key linking this dispatch to the agent’s run_started telemetry.
Correlation key linking this dispatch to the agent’s run_started telemetry.
`status`	string	Yes	queued \| queued_offline
queued \| queued_offline

400 Code invalid_argument: the request was malformed or failed validation. The api rejects a body that names neither job_name nor source_slug, and a body whose job_name and source_slug disagree (the job does not belong to that source). Nothing is dispatched.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 Code not_found: the project does not exist, or the job named by job_name (or the source named by the deprecated source_slug) does not exist in the environment. Nothing is dispatched.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The run cannot be dispatched in the project's current state. Nothing is dispatched. The causes are: the control plane has no agent channel (code conflict); the project has no assigned agent, or its agent is not reachable (code conflict); the project is archived (code conflict); the body names the deprecated source_slug only and the source has more than one job (code conflict); the agent is below the execute-by-job floor and the job shares its source with other jobs (code agent_upgrade_required); the run's strategy is incremental and the agent is below the incremental floor, or reports no readable version (code agent_upgrade_required); the platform is still provisioning the environment's repository, or its last attempt failed (code repository_required).

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/repository/move`

Read the project's latest repository check or move.

Returns the latest check (a dry run) or move of the project’s repository to the customer’s own repository (api#1090, R24): its state, what the check found, and each branch’s progress while a move runs. A client polls it while the state is moving or adopting. The token is never returned. 404 when the project had no check or move.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

200 The project's latest check or move.

application/json

Property	Type	Required	Description
`branches`	RepositoryMoveBranch []	Yes	Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
`configuration`	RepositoryMoveConfiguration	No

`differences`	RepositoryMoveDifference []	No	Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
`display_name`	string	Yes	The target repository’s display name.
The target repository’s display name.
`earlier_partial_move`	string[]	No	Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
`error`	Error	No

`finished_at`	string	No	When the check or move ended. Absent while it runs.
When the check or move ended. Absent while it runs.
`git_repo_url`	string	Yes	The target repository’s address.
The target repository’s address.
`kind`	string	No	move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
`missing_connections`	RepositoryMoveConnection []	No	Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
`paused_until`	string	No	Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
`proposals`	string	No	For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
`running`	boolean	No	True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
`started_at`	string	Yes	When the check or move began.
When the check or move began.
`starting_point`	string	Yes	The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
`state`	RepositoryMoveState	Yes

`target`	string	No	What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
`unmapped_branches`	string[]	No	Target branches that map to no bound environment; they are ignored and left as they are.
Target branches that map to no bound environment; they are ignored and left as they are.
`unreadable_files`	string[]	No	Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).
Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/repository/move`

Check or move the project's repository to the customer's own repository.

Moves the project’s configuration repository to a repository the customer owns, for every environment at once (api#1090, R24, ADR-160: one repository per project). It starts from the managed repository, from another customer repository, from a managed repository whose creation failed, or from no repository where no git host is configured (S13, S17, S19). Only an owner or admin may call it.

With dry_run true it is the check (D3): it tests the token, reads the target and the project, and answers 200 with what a move would do or why it is refused (state checked or refused, error naming the code). It changes no configuration and no repository. While it runs, and for 15 minutes after a check found the target usable, the automatic retry of a failed managed repository pauses (S18); a refused check ends the pause, and so does DELETE.

Only the configuration paths decide what happens (S11): amfelt.yaml and the data contract files. A target without them (empty, or other files only) receives the project’s full history and every environment branch; a branch the target already has is joined with a commit that has both tips as parents, so both histories are kept and nothing is removed. A target with a readable configuration is adopted (S16, S16a): one new commit on main with two parents, the earlier main and the customer’s, so every pinned version stays reachable; main and Development take the customer’s configuration through the ADR-130 import (all or nothing); every other bound environment keeps its pinned branch, and the customer’s branch for it waits in proposal/<environment> for a promotion. Connections that differ in the adopted branches are reported, never applied. A target whose configuration files cannot be read is refused, naming them.

Without dry_run the same checks run first and refuse with their code; then the move runs in the background and the answer is 202 with state moving or adopting. Publishing waits while it runs. On success every environment uses the new repository at the same commits and the managed repository is archived with its history (a customer’s previous repository is left as it is). A move that fails leaves the project on its repository; branches already pushed stay and are reported, and the next check shows them as an earlier partial move.

It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus). An adoption imports the customer’s jobs and objects, but classification and PII-label state inline in the customer’s contract files is not taken: every contract it stores takes the stored state by object and property identity (ClassificationStatus). A history-mode change that the adopted configuration brings is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Request body (required)

application/json

Property	Type	Required	Description
`display_name`	string	No	The repository’s display name; the last part of the URL when absent.
The repository’s display name; the last part of the URL when absent.
`dry_run`	boolean	No	true runs the check only (D3): nothing changes, and the answer is 200 with the verdict.
true runs the check only (D3): nothing changes, and the answer is 200 with the verdict.
`git_repo_url`	string	Yes	The HTTPS address of one git repository on a host that supports git-https/v1, for example https://git.example.com/acme/config . It carries no credential.
The HTTPS address of one git repository on a host that supports git-https/v1, for example https://git.example.com/acme/config . It carries no credential.
`token`	string	Yes	An access token with read and write access to the repository contents.
An access token with read and write access to the repository contents.

Responses

200 The check's verdict (dry_run true).

application/json

Property	Type	Required	Description
`branches`	RepositoryMoveBranch []	Yes	Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
`configuration`	RepositoryMoveConfiguration	No

`differences`	RepositoryMoveDifference []	No	Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
`display_name`	string	Yes	The target repository’s display name.
The target repository’s display name.
`earlier_partial_move`	string[]	No	Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
`error`	Error	No

`finished_at`	string	No	When the check or move ended. Absent while it runs.
When the check or move ended. Absent while it runs.
`git_repo_url`	string	Yes	The target repository’s address.
The target repository’s address.
`kind`	string	No	move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
`missing_connections`	RepositoryMoveConnection []	No	Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
`paused_until`	string	No	Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
`proposals`	string	No	For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
`running`	boolean	No	True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
`started_at`	string	Yes	When the check or move began.
When the check or move began.
`starting_point`	string	Yes	The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
`state`	RepositoryMoveState	Yes

`target`	string	No	What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
`unmapped_branches`	string[]	No	Target branches that map to no bound environment; they are ignored and left as they are.
Target branches that map to no bound environment; they are ignored and left as they are.
`unreadable_files`	string[]	No	Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).
Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).

202 The move started (dry_run false); poll GET for its progress.

application/json

Property	Type	Required	Description
`branches`	RepositoryMoveBranch []	Yes	Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
`configuration`	RepositoryMoveConfiguration	No

`differences`	RepositoryMoveDifference []	No	Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
`display_name`	string	Yes	The target repository’s display name.
The target repository’s display name.
`earlier_partial_move`	string[]	No	Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
`error`	Error	No

`finished_at`	string	No	When the check or move ended. Absent while it runs.
When the check or move ended. Absent while it runs.
`git_repo_url`	string	Yes	The target repository’s address.
The target repository’s address.
`kind`	string	No	move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
`missing_connections`	RepositoryMoveConnection []	No	Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
`paused_until`	string	No	Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
`proposals`	string	No	For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
`running`	boolean	No	True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
`started_at`	string	Yes	When the check or move began.
When the check or move began.
`starting_point`	string	Yes	The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
`state`	RepositoryMoveState	Yes

`target`	string	No	What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
`unmapped_branches`	string[]	No	Target branches that map to no bound environment; they are ignored and left as they are.
Target branches that map to no bound environment; they are ignored and left as they are.
`unreadable_files`	string[]	No	Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).
Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The move is refused (dry_run false), or another move runs (both): repository_moving (a move of this project runs), repository_in_use (this project or another project in the organization uses the target), repository_environments_differ (the environments use different repositories; join them first, ADR-160 decision 13), repository_not_ready (the managed repository is being created), repository_changed (the project's repository changed since the check, for example the automatic retry created it), configuration_unreadable (the message names the files), configuration_incomplete (the configuration lacks amfelt.yaml on main or development, lives only on a pinned environment's branch, or has no jobs while Development has some; the message names what is missing), connections_missing (the message names the sources and data platforms to connect first, S4), path_conflict (a path is a file on one side and a directory on the other; the message names it), project_archived (the project is archived), conflict (the project has no environment).

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

422 The target refused the token (dry_run false): token_rejected, token_read_only (the token can read but not write), repository_not_found, or repository_too_large (the branches to read exceed the deployment's transfer limit, 500 MB by default, or hold an object larger than its object limit, 64 MB by default; the message names the limit, and a configuration file past 10 MB by its path).

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

502 The target's git host did not answer (dry_run false), code repository_unreachable.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

503 The deployment is busy with other checks and moves (both): code move_busy. The disk the moves share is in use, or the organization runs as many checks and moves as it may at once. Try again shortly.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/repository/move`

Cancel the repository flow.

Ends the project’s check or failed move as cancelled, which ends the pause of the automatic retry at once (S18). Branches a failed move pushed stay in the target. A running check, and a move whose run was interrupted, end as cancelled. Only an owner or admin may cancel. 404 when the project had no check or move; 409 repository_moving while a move runs, which cannot be cancelled, and 409 conflict for a finished move (moved or adopted). It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

204 Cancelled; the automatic retry resumes.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/platform/test`

Test the project's data-platform connection.

Dispatches cmd.test_connection with kind platform to the project’s pinned agent over the icpc channel, for the requested environment’s saved data-platform connection. The agent resolves the saved credentials through the vault (ADR-037) and calls the target connector’s connection test, which opens a connection to the data platform and, in one transaction the database then rolls back, tries each kind of create that provisioning runs. Only the saved configuration is tested. Returns the dispatch command id for correlation. The result is not in this response: the agent reports it over event.cmd_finished, and it is read back through the agent command-outcome projection (AgentCommandOutcome), with the result code in reason and the message in message. A passing result has state done; a failing one has state failed. The data-platform read also returns the latest test as last_test, failures included, with a pending flag that is true while the latest test has no recorded answer; a passing answer makes a configured connection verified.

What a success means (ADR-147 decision 1). The saved configuration connects: the target is reachable, its access rules admit the connection, it accepts the credentials, the role may log in and connect, the database exists, and the role holds USAGE on each existing layer schema. And, in a trial the database rolled back, the target accepted each kind of create that provisioning runs: a schema, when the trial creates one, and a table, a view and an index in each existing layer schema. For DuckDB, an existing database file opened read-write and accepted the trial and its directory accepts a new file; for an absent file, its directory accepts a new file. A success is not a promise that the next deploy succeeds. These are outside the test and are reported by deploy and runs: ownership of views or tables another role created, objects that depend on a job’s contract, changes made after the test, and layer schemas created under a --schema-prefix override.

Result codes. Each code is spelled exactly as the connector SDK defines it. Three results pass, each with state done:

ok — every check passed. The message lists each layer schema as accessible or not yet created.

no_layer_schemas_yet — every check passed and no layer schema exists. The message carries the note “Connected. No layer schemas yet — the first deploy creates them and reports any missing rights.”

no_database_file_yet — DuckDB only: every check for an absent database file passed. The message carries the note “Connected. The database file does not exist yet — the first deploy creates it at <path>.”, with the full resolved path in place of <path>.

The failing results, each with state failed:

unreachable — the connector tried to reach the target and could not before its own deadline, a failed host-name lookup included.

credentials_rejected — the target checked the credentials and rejected them, such as a wrong password or an unknown user.

database_missing — the database the configuration names does not exist.

no_access — the target refused a right needed to use the database or to read a layer schema, the DuckDB file or its path, or its access rules refused the connection.

cannot_create — the target refused a right needed to create objects. The message names the statement class and schema, or the path.

target_busy — another session or process holds a lock the test needs; the message leads with “in use — try again when it finishes”. Retryable.

timed_out — the connector had contacted the target and its own deadline passed before the checks finished. Retryable.

other_failure — the target was never contacted, the agent’s call to the connector failed in transport or passed the agent’s 30-second deadline, or no rule classifies the failure. Set by the connector or the agent.

not_supported — not supported by this connector: the target connector does not implement the connection test. Set by the agent.

Only target_busy and timed_out are marked retryable. Not supported by this agent is not a result code, because the api decides it before anything is dispatched: see the 409 response. An agent that predates the target test and receives the frame anyway answers with state failed: reason platform_probe_unsupported from v4.10.0 through v4.10.x, and reason no_handler from v4.1.0 through v4.9.x. Any other reason means the agent refused or lost the command itself (for example invalid_request), not that the test ran.

The message. As they apply, the message carries the driver’s text verbatim, the refused statement class and schema, the result’s note, each layer schema’s state, and a sentence naming the bound when a deadline ended the attempt. Whatever the result, it also carries the path of any temp file the test left behind. It is diagnostic text rather than operator copy: branch on the code, not on the message.

Access. Gated on projects.update, the permission that configures the data-platform connection. The policy defaults grant it to owner and admin and not to operator, so an operator receives 403.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`env`	query	No	string	DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.
DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.

Responses

202 Connection test dispatched. The result arrives later, through the agent command-outcome projection, under the returned command id, and in the data-platform read's `last_test`.

application/json

Property	Type	Required	Description
`command_id`	string	Yes	The dispatched command id, for correlating run events.
The dispatched command id, for correlating run events.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller lacks projects.update (code=permission_denied). The policy defaults grant it to owner and admin, not to operator.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The test was not dispatched (code=conflict). Among the causes: the data-platform connection has no stored credentials, the project has no pinned agent, or the agent is not reachable. When the pinned agent predates the release that carries the target test (agent v4.11.0), the test is not supported by this agent, and the message says so as the source probe spells it: "connection test is not supported by this agent; upgrade it to <version> or later".

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/platform`

Get the project's data-platform connection.

Returns the non-secret view of the project’s target data-platform connection for the requested environment, resolved from the vault. The stored secret is never returned.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`env`	query	No	string	DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.
DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.

Responses

200 The project's data-platform connection.

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the platform.
Agent type connecting to the platform.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, account, database, schema, warehouse). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, account, database, schema, warehouse). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`last_test`	LastConnectionTest	No

`name`	string	Yes	Human-readable platform name.
Human-readable platform name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, error. Never ‘failing’: a run failure may have failed source-side and is not evidence the target platform is unhealthy. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest successful run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active. A passing test that is newer makes it verified. A failing test that is newer makes it configured, with the failure’s result code and message in last_test; a later successful run takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the connection’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active when a successful run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, error. Never ‘failing’: a run failure may have failed source-side and is not evidence the target platform is unhealthy. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest successful run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active. A passing test that is newer makes it verified. A failing test that is newer makes it configured, with the failure’s result code and message in last_test; a later successful run takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the connection’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active when a successful run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘snowflake’.
Connector type slug, e.g. ‘snowflake’.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/platform`

Configure the project's data-platform connection.

Registers or updates the target data-platform connection (vault-first) for the requested environment and upserts the identity row. Secret fields are write-only. A history-mode change that a change of the platform brings to the runs is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves. It answers no history_rebuild_required and takes no rebuild_history.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`env`	query	No	string	DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.
DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.

Request body (required)

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the platform.
Agent type connecting to the platform.
`config`	object	No	Non-secret connection fields (host, port, account, database, schema, warehouse).
Non-secret connection fields (host, port, account, database, schema, warehouse).
`name`	string	Yes	Human-readable platform name.
Human-readable platform name.
`secret`	object	No	Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
`type`	string	Yes	Connector type slug, e.g. ‘snowflake’.
Connector type slug, e.g. ‘snowflake’.

Responses

200 The configured data-platform connection.

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the platform.
Agent type connecting to the platform.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, account, database, schema, warehouse). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, account, database, schema, warehouse). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`last_test`	LastConnectionTest	No

`name`	string	Yes	Human-readable platform name.
Human-readable platform name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, error. Never ‘failing’: a run failure may have failed source-side and is not evidence the target platform is unhealthy. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest successful run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active. A passing test that is newer makes it verified. A failing test that is newer makes it configured, with the failure’s result code and message in last_test; a later successful run takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the connection’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active when a successful run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, error. Never ‘failing’: a run failure may have failed source-side and is not evidence the target platform is unhealthy. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest successful run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active. A passing test that is newer makes it verified. A failing test that is newer makes it configured, with the failure’s result code and message in last_test; a later successful run takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the connection’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active when a successful run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘snowflake’.
Connector type slug, e.g. ‘snowflake’.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/platform`

Delete the project's data-platform connection.

Permanently removes the requested environment’s target data-platform connection and its vault entry (irreversible). With the connector type immutable, deleting and reconfiguring is the only way to change a platform’s type.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`env`	query	No	string	DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.
DTAP environment slug to scope the request to. Must name an environment the project is bound to. When omitted the server falls back to the project’s primary bound environment (lowest DTAP sort order), which is the pre-existing behavior.

Responses

204 The data platform was permanently deleted.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/members`

List a project's members.

Returns the members of a project with their project rank role.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`cursor`	query	No	string	Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
`limit`	query	No	integer	Maximum number of items to return per page.
Maximum number of items to return per page.

Responses

200 A page of project members.

application/json

Property	Type	Required	Description
`data`	ProjectMember []	Yes	The page of members.
The page of members.
`next_cursor`	[string null]	No	Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.
Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/members`

Add a member to a project.

Adds an existing organization member to a project with a project rank role. The account must already be an active member of the organization that owns the project.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Request body (required)

application/json

Property	Type	Required	Description
`account_id`	string	Yes	Identifier of the account to add. Must be an active member of the organization that owns the project.
Identifier of the account to add. Must be an active member of the organization that owns the project.
`role`	ProjectRole	Yes

Responses

201 The member was added to the project.

application/json

Property	Type	Required	Description
`account_id`	string	Yes	Identifier of the member’s account.
Identifier of the member’s account.
`email`	string	Yes	Email address of the member.
Email address of the member.
`first_name`	string	No	Given name of the member.
Given name of the member.
`id`	string	Yes	Identifier of the project membership.
Identifier of the project membership.
`joined_at`	string	Yes	Timestamp the member joined the project.
Timestamp the member joined the project.
`last_name`	string	No	Family name of the member.
Family name of the member.
`role`	ProjectRole	Yes

`status`	string	Yes	Status of the membership. Examples: `active`.
Status of the membership. Examples: `active`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/jobs`

List a project's jobs.

Returns the configured jobs for the project in the given environment (ADR-074).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The project's jobs in the given environment.

application/json

Property	Type	Required	Description
`data`	Job []	Yes	The jobs.
The jobs.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/jobs`

Create a project job.

Atomically creates a complete job document under a name that is not already used in the project and environment. Unlike PUT on the named job resource, this operation never replaces an existing job; a name collision returns 409 Conflict. A new job can select an object whose history already exists on the job’s target in another history mode; such a create answers 409 history_rebuild_required and creates nothing, unless the body sets rebuild_history; confirmed, it records a pending history rebuild of each such object on that target for its next run (HistoryRebuildConflict). A job never sets classification or PII-label state: the stored state is carried over (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`name`	string	Yes	Job name.
Job name.
`rebuild_history`	boolean	No	Confirms that the new job may change the history mode of objects whose history already exists on its target, dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a job is not created: the request answers 409 history_rebuild_required. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
Confirms that the new job may change the history mode of objects whose history already exists on its target, dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a job is not created: the request answers 409 history_rebuild_required. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	Name of the project source this job reads from.
Name of the project source this job reads from.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.

Responses

201 The created job.

application/json

Property	Type	Required	Description
`name`	string	Yes	Job name.
Job name.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	ADR-067 cross-plane key; equals the PCF sources[].name.
ADR-067 cross-plane key; equals the PCF sources[].name.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.
`updated_at`	string	No	When the job was last updated.
When the job was last updated.
`warnings`	JobWarning []	No	Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.
Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.

400 The request was malformed or failed validation. Code job_validation_failed: one or more objects in select.objects failed validation; objects names each object, the field and the cause, and nothing is created. Any other code is the standard Error.

application/json

Property	Type	Required	Description
`code`	string	Yes	As Error.code; job_validation_failed when objects fail validation. Examples: `job_validation_failed`.
As Error.code; job_validation_failed when objects fail validation. Examples: `job_validation_failed`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	JobObjectValidationError []	No	Set with code job_validation_failed; one entry per failing object.
Set with code job_validation_failed; one entry per failing object.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 Code conflict: a job with this name already exists. Code history_rebuild_required: the job would change the history mode of objects whose history already exists on its target; objects names them. Nothing is created.

application/json

Property	Type	Required	Description
`code`	string	Yes	As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	HistoryModeChange []	No	Set with code history_rebuild_required; the objects the change would rebuild.
Set with code history_rebuild_required; the objects the change would rebuild.

Security

bearer_jwt

GET `/v1/projects/{id}/environments`

List a project's environments.

The DTAP environments the project is bound to, in promotion order.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

200 The project's environments.

application/json

Property	Type	Required	Description
`data`	ProjectEnvironment []	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments`

Bind a project to an environment.

Configures the project in a DTAP slot.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Request body (required)

application/json

Property	Type	Required	Description
`environment_id`	string	Yes	The DTAP environment slug to bind.
The DTAP environment slug to bind.

Responses

201 The environment was bound.

application/json

Property	Type	Required	Description
`agent_commit_reported_at`	[string null]	No	When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
`agent_commit_sha`	[string null]	No	Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`agent_id`	[string null]	No	The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
`deployed_commit_sha`	[string null]	No	Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`environment_id`	string	Yes	The DTAP environment slug.
The DTAP environment slug.
`id`	string	Yes	Binding identifier.
Binding identifier.
`name`	string	Yes	Environment display name.
Environment display name.
`project_id`	string	Yes	The project.
The project.
`sort_order`	integer	Yes	DTAP promotion order (ascending).
DTAP promotion order (ascending).

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/archive`

Disable (archive) a project.

Soft-disables a project (reversible). Archived projects are hidden from active lists.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

200 The archived project.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/agent`

Assign a project's executing agent.

Pins an agent as the project’s executing agent (exec.project.agent_id). The agent must be active and belong to the same tenant.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Request body (required)

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	The agent to pin as the executing agent — must be an active agent in the same tenant.
The agent to pin as the executing agent — must be an active agent in the same tenant.

Responses

200 The updated project with the assigned agent.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

422 The request was well-formed but failed semantic validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/agent`

Clear a project's executing agent.

Removes the pinned executing agent from the project, setting exec.project.agent_id to null.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

200 The updated project with the agent cleared.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}`

Get a project.

Returns a single project by id within the caller’s active tenant.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

200 The project.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PATCH `/v1/projects/{id}`

Update a project.

Updates a project’s mutable settings (its display name and its time zone).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Request body (required)

application/json

Property	Type	Required	Description
`display_name`	string	Yes	New human-readable name for the project.
New human-readable name for the project.
`time_zone`	string	No	New IANA time zone name for the project. Omitted, the project keeps its time zone. Examples: `Europe/Amsterdam`.
New IANA time zone name for the project. Omitted, the project keeps its time zone. Examples: `Europe/Amsterdam`.

Responses

200 The updated project.

application/json

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

400 Code invalid_argument: the request was malformed or failed validation. A time_zone that is not an IANA time zone name answers with field=time_zone. Nothing changes.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}`

Permanently delete a project.

Hard-deletes a project and its environment bindings (irreversible). Writes a deletion-audit record.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.

Responses

204 The project was permanently deleted.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/sources/{source_id}/test`

Test a project's data-source connection.

Dispatches cmd.test_connection to the project’s pinned agent over the icpc channel; the agent resolves the stored credentials through the vault (ADR-037) and opens the connection, reporting the outcome — and the driver’s own error text on failure — over event.cmd_finished. Returns the dispatch command id for correlation. The result is read back through the agent command-outcome projection, not from this response. The source read also returns the latest test as last_test, failures included, with a pending flag that is true while the latest test has no recorded answer; a passing answer makes a configured connection verified. The environment is taken from the stored source, so no env parameter is accepted. When a passing answer arrives for a source with no catalog contract in its environment, onboarding dispatches a discover by itself, also when the caller lacks catalog.write, and the source read reports it as auto_discover; when that discover finishes, the source read reports the created job as first_job.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`source_id`	path	Yes	string	Data source identifier.
Data source identifier.

Responses

202 Connection test dispatched.

application/json

Property	Type	Required	Description
`command_id`	string	Yes	The dispatched command id, for correlating run events.
The dispatched command id, for correlating run events.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/sources/{source_id}`

Get a project's data source.

Returns the non-secret view of a single data-source connection, resolved from the vault. The stored secret is never returned.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`source_id`	path	Yes	string	Data source identifier.
Data source identifier.

Responses

200 The data source.

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`auto_discover`		No	The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`first_job`		No	The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
`id`	string	Yes	Data source identifier.
Data source identifier.
`last_test`	LastConnectionTest	No

`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.
`updated_at`	string	Yes	When the data source’s configuration last changed. Recording a connection test does not move it.
When the data source’s configuration last changed. Recording a connection test does not move it.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/sources/{source_id}`

Update a project's data source.

Updates the data-source connection (vault-first). Secret fields are write-only.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`source_id`	path	Yes	string	Data source identifier.
Data source identifier.

Request body (required)

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`config`	object	No	Non-secret connection fields (host, port, database, schema).
Non-secret connection fields (host, port, database, schema).
`secret`	object	No	Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.

Responses

200 The updated data source.

application/json

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`auto_discover`		No	The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`first_job`		No	The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
`id`	string	Yes	Data source identifier.
Data source identifier.
`last_test`	LastConnectionTest	No

`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.
`updated_at`	string	Yes	When the data source’s configuration last changed. Recording a connection test does not move it.
When the data source’s configuration last changed. Recording a connection test does not move it.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/sources/{source_id}`

Delete a project's data source.

Permanently removes the data-source connection and its vault entry (irreversible).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`source_id`	path	Yes	string	Data source identifier.
Data source identifier.

Responses

204 The data source was permanently deleted.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PATCH `/v1/projects/{id}/members/{account_id}`

Update a project member's role.

Re-assigns the member’s project rank role.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`account_id`	path	Yes	string	Identifier of the member’s account.
Identifier of the member’s account.

Request body (required)

application/json

Property	Type	Required	Description
`role`	ProjectRole	Yes

Responses

200 The updated project member.

application/json

Property	Type	Required	Description
`account_id`	string	Yes	Identifier of the member’s account.
Identifier of the member’s account.
`email`	string	Yes	Email address of the member.
Email address of the member.
`first_name`	string	No	Given name of the member.
Given name of the member.
`id`	string	Yes	Identifier of the project membership.
Identifier of the project membership.
`joined_at`	string	Yes	Timestamp the member joined the project.
Timestamp the member joined the project.
`last_name`	string	No	Family name of the member.
Family name of the member.
`role`	ProjectRole	Yes

`status`	string	Yes	Status of the membership. Examples: `active`.
Status of the membership. Examples: `active`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/members/{account_id}`

Remove a member from a project.

Removes the account’s membership of the project. The organization membership is unaffected.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`account_id`	path	Yes	string	Identifier of the member’s account.
Identifier of the member’s account.

Responses

204 The member was removed from the project.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/jobs/{job_name}`

Get a project's job.

Returns a single job’s complete document (source, select, runs), keyed by project + environment + job name (ADR-074).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`job_name`	path	Yes	string	Job name.
Job name.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The job.

application/json

Property	Type	Required	Description
`name`	string	Yes	Job name.
Job name.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	ADR-067 cross-plane key; equals the PCF sources[].name.
ADR-067 cross-plane key; equals the PCF sources[].name.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.
`updated_at`	string	No	When the job was last updated.
When the job was last updated.
`warnings`	JobWarning []	No	Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.
Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/jobs/{job_name}`

Create or replace a job.

Upserts the complete job document (source, select, runs), keyed by project + environment + job name (ADR-074). Create-or-replace semantics — a PUT to an absent job creates it; a PUT to an existing job fully replaces it, including its runs and object overrides. A replacement that changes the history mode of an object whose history already exists on the job’s target answers 409 history_rebuild_required and changes nothing, unless the body sets rebuild_history; confirmed, it records a pending history rebuild of each such object on that target for its next run (HistoryRebuildConflict). A job never sets classification or PII-label state: the stored state is carried over (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`job_name`	path	Yes	string	Job name.
Job name.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`rebuild_history`	boolean	No	Confirms that the replacement may change the history mode of objects whose history already exists on a target (through select.objects or select.defaults), dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a replacement answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
Confirms that the replacement may change the history mode of objects whose history already exists on a target (through select.objects or select.defaults), dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a replacement answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	ADR-067 cross-plane key; equals the PCF sources[].name.
ADR-067 cross-plane key; equals the PCF sources[].name.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.

Responses

200 The upserted job.

application/json

Property	Type	Required	Description
`name`	string	Yes	Job name.
Job name.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	ADR-067 cross-plane key; equals the PCF sources[].name.
ADR-067 cross-plane key; equals the PCF sources[].name.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.
`updated_at`	string	No	When the job was last updated.
When the job was last updated.
`warnings`	JobWarning []	No	Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.
Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.

application/json

Property	Type	Required	Description
`code`	string	Yes	As Error.code; job_validation_failed when objects fail validation. Examples: `job_validation_failed`.
As Error.code; job_validation_failed when objects fail validation. Examples: `job_validation_failed`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	JobObjectValidationError []	No	Set with code job_validation_failed; one entry per failing object.
Set with code job_validation_failed; one entry per failing object.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 Code history_rebuild_required: the replacement would change the history mode of objects whose history already exists on its target; objects names them. Nothing is changed.

application/json

Property	Type	Required	Description
`code`	string	Yes	As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	HistoryModeChange []	No	Set with code history_rebuild_required; the objects the change would rebuild.
Set with code history_rebuild_required; the objects the change would rebuild.

Security

bearer_jwt

DELETE `/v1/projects/{id}/jobs/{job_name}`

Delete a project's job.

Permanently removes the job, its runs, and its object overrides (irreversible), keyed by project + environment + job name (ADR-074).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`job_name`	path	Yes	string	Job name.
Job name.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

204 The job was permanently deleted.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/status`

List a project's server statuses for an environment.

Returns the configured servers’ status rows for a project in the given environment.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug (development
DTAP environment slug (development

Responses

200 The project's server statuses.

application/json

Property	Type	Required	Description
`data`	ServerStatus []	Yes	The status rows.
The status rows.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo/tree/entries`

List the committed config tree.

Returns every file in the committed tree at ref (or at the branch tip when ref is omitted), with its artifact class and size. Never returns file content — see the file endpoint. Returns 404 when no repo is bound.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`ref`	query	No	string	Commit SHA to read the tree at. Must resolve within the branch’s history. Omitted means the branch tip.
Commit SHA to read the tree at. Must resolve within the branch’s history. Omitted means the branch tip.
`include`	query	No	string[]	Derived fields to compute for this read. Omitted means the default response, which costs one clone. Each value names a field that requires additional work, so a caller opts into that cost deliberately rather than paying it on every read.
Derived fields to compute for this read. Omitted means the default response, which costs one clone. Each value names a field that requires additional work, so a caller opts into that cost deliberately rather than paying it on every read.

Responses

200 The committed tree.

application/json

Property	Type	Required	Description
`entries`	RepoTreeEntry []	Yes	One entry per file. Empty when the branch has no commits yet.
One entry per file. Empty when the branch has no commits yet.
`head_sha`	string	Yes	The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
`modified_at_truncated`	boolean	No	Present only when include=modified_at was requested. True means the history walk exhausted its budget while paths were still undated, so a null modified_at means “we stopped looking” rather than “no commit touched this path”. False means the walk reached the end of history, and any remaining null is a genuine absence. Without this flag the two cases are indistinguishable, and a client cannot tell a user which one it is looking at.
Present only when include=modified_at was requested. True means the history walk exhausted its budget while paths were still undated, so a null modified_at means “we stopped looking” rather than “no commit touched this path”. False means the walk reached the end of history, and any remaining null is a genuine absence. Without this flag the two cases are indistinguishable, and a client cannot tell a user which one it is looking at.
`ref`	string	Yes	The commit the entries were read at. Echoed back so a client can pin follow-up file reads to the same commit — a (ref, path) pair is immutable and therefore safe to cache.
The commit the entries were read at. Echoed back so a client can pin follow-up file reads to the same commit — a (ref, path) pair is immutable and therefore safe to cache.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo/tree`

Read the committed config tree from Git (git-lite pull).

Returns the environment’s committed config files at ref (or at the branch tip when ref is omitted) and the branch HEAD SHA, for the agent to materialize into its local working copy (ADR-066 §4).

head_sha always reports the branch tip, even when ref pins an older commit. Comparing it against the ref that was requested is how a caller detects that the branch moved while it was working (ADR-129 decision 5).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
`ref`	query	No	string	Commit SHA to read the tree at. Must resolve within the branch’s history. Omitted means the branch tip.

This is a commit SHA, not a branch or tag name: a name that is not a well-formed hash is rejected the same way an absent commit is, so passing a branch name fails rather than resolving to its tip. |

Responses

200 The committed config tree.

application/json

Property	Type	Required	Description
`base_sha`	string	Yes	DEPRECATED — use head_sha, which holds the same value under the name the rest of this schema family uses. This field is the branch tip. It does NOT mean what RepoStatus.base_sha means: there, base_sha is the last SHA the control plane pushed, deliberately not the tip, and external_change is defined as the two differing. Removal waits for a major version.
DEPRECATED — use head_sha, which holds the same value under the name the rest of this schema family uses. This field is the branch tip. It does NOT mean what RepoStatus.base_sha means: there, base_sha is the last SHA the control plane pushed, deliberately not the tip, and external_change is defined as the two differing. Removal waits for a major version.
`files`	ConfigFile []	Yes

`head_sha`	string	No	The branch tip commit SHA. Matches RepoStatus.head_sha and RepoTreeEntries.head_sha.
The branch tip commit SHA. Matches RepoStatus.head_sha and RepoTreeEntries.head_sha.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 No repo is bound for this environment (code=not_found), or ref does not resolve in this branch's history (code=ref_not_found). Both mean "the thing you asked for does not exist" and carry DISTINCT codes: a client that collapses them cannot tell "never connected" from "your pinned ref was force-pushed away". Matches the tree/entries endpoint.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo/status`

Working-copy status vs the committed config.

Returns the git binding, HEAD and base SHAs, whether the repo changed out-of-band, and a per-file line diff of the current authored config (overlay) against the committed tree. Returns 404 when no repo is bound and none is being provisioned. While the platform provisions the environment’s managed repository (ADR-129 decision 11) and it holds no commit for the environment yet, the answer is 200 with the binding (managed, status pending or failed), no head_sha or base_sha, not dirty, no external change and no files: there is no version yet.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The working-copy status.

application/json

Property	Type	Required	Description
`base_sha`	string	No	The last SHA the control plane pushed (exec.project_environment.git_base_sha). Empty until the first commit.
The last SHA the control plane pushed (exec.project_environment.git_base_sha). Empty until the first commit.
`binding`	RepoBindingView	No

`dirty`	boolean	Yes	True when the authored overlay differs from the committed tree.
True when the authored overlay differs from the committed tree.
`external_change`	boolean	Yes	True when head_sha differs from base_sha — someone committed out-of-band (e.g. the CLI).
True when head_sha differs from base_sha — someone committed out-of-band (e.g. the CLI).
`files`	RepoStatusFile []	Yes	One entry per changed file. Empty when up to date.
One entry per changed file. Empty when up to date.
`head_sha`	string	No	Current branch HEAD SHA. Empty when the branch has no commits yet.
Current branch HEAD SHA. Empty when the branch has no commits yet.
`objects`	RepoStatusObject []	No	The changed objects, grouped from the same working copy the files array describes — both are projections of one diff, never two diffs. Absent when HEAD could not be parsed into job/object structure (e.g. an out-of-band commit left invalid YAML); files remains authoritative in that case.
The changed objects, grouped from the same working copy the files array describes — both are projections of one diff, never two diffs. Absent when HEAD could not be parsed into job/object structure (e.g. an out-of-band commit left invalid YAML); files remains authoritative in that case.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/sql/render-result`

Ingest a rendered generated-SQL tree (agent-auth).

The agent posts the SQL it rendered for a named commit; the control plane composes the sql/ tree and commits it (ADR-127 decisions 4 and 5, which make the control plane the only writer). The org is derived from the agent JWT, never the body. While the project’s repository moves to the customer’s own (api#1090) the commit waits: 409 with code repository_moving; when the repository changed between the read of the binding and the push, 409 with code repository_changed, and nothing is pushed. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`command_id`	string	Yes	The command_id from the cmd.render_sql frame this answers.
The command_id from the cmd.render_sql frame this answers.
`error`	string	No	Why the render failed. Required when status is failed.
Why the render failed. Required when status is failed.
`objects`	SqlRenderedObject []	No

`plugin_version`	string	No	The plugin@version that produced this render, as core/sql stamps into every header.
The plugin@version that produced this render, as core/sql stamps into every header.
`ref`	string	Yes	The commit SHA the agent actually rendered.
The commit SHA the agent actually rendered.
`status`	string	Yes	rendered means objects is authoritative and MAY legitimately be empty, which prunes the tree. failed means the render did not complete and objects must be ignored entirely. These are distinct because an empty object list is a valid render outcome, so a caller cannot infer failure from it. Valid values are: `rendered`, `failed`.
rendered means objects is authoritative and MAY legitimately be empty, which prunes the tree. failed means the render did not complete and objects must be ignored entirely. These are distinct because an empty object list is a valid render outcome, so a caller cannot infer failure from it. Valid values are: `rendered`, `failed`.

Responses

200 The result was accepted. A commit may or may not have been produced.

application/json

Property	Type	Required	Description
`commit_sha`	string	Yes	The created commit SHA. Empty when the commit was a no-op (no changes to push).
The created commit SHA. Empty when the commit was a no-op (no changes to push).
`files`	string[]	Yes	Repo-relative paths written by the commit.
Repo-relative paths written by the commit.
`outcome`	string	Yes	What the ingest actually did with the render. committed means a follow-up commit landed. no_change means the result was accepted and there was nothing to commit. discarded_stale means the render described a commit that is no longer the branch tip, so it was discarded — nothing re-dispatches it, which is why this outcome exists to surface: a discarded render is otherwise silent. Valid values are: `committed`, `no_change`, `discarded_stale`.
What the ingest actually did with the render. committed means a follow-up commit landed. no_change means the result was accepted and there was nothing to commit. discarded_stale means the render described a commit that is no longer the branch tip, so it was discarded — nothing re-dispatches it, which is why this outcome exists to surface: a discarded render is otherwise silent. Valid values are: `committed`, `no_change`, `discarded_stale`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/sql/render`

Trigger a generated-SQL render for the environment's current branch tip.

Dispatches cmd.render_sql to the project’s assigned agent, which renders the generated SQL at a commit the control plane chooses — the caller supplies no body — and posts the result back via the render-result ingest endpoint (ADR-127). Returns the dispatch command id for correlation. Dispatch is asynchronous: a 202 means the command was accepted for delivery, not that SQL was produced. Returns 404 when the project or its repository binding does not exist, and 409 when the project has no assigned agent, no open agent channel, or the agent is unreachable. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

202 Render dispatched.

application/json

Property	Type	Required	Description
`command_id`	string	Yes	The dispatched command id, for correlating run events.
The dispatched command id, for correlating run events.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/retry`

Retry a failed managed repository creation.

Starts one more attempt to create the environment’s managed repository (ADR-129 decision 11) now, next to the automatic retry. The attempt runs in the background: the answer is 202 with the binding view in status pending, and a later GET …/repo shows ready, or failed when the attempt failed again. Only an owner or admin may retry (403 otherwise). 404 when the project or the environment does not exist or the environment is not bound to the project. 409 when the repository is not failed: it is pending (an attempt runs or is due), ready, the customer’s own, or was never provisioned; 409 when this deployment provisions no repositories (no platform git host is configured); and 409 with code repository_moving while a check or move of the project’s repository pauses the retry (api#1090, S18). It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

202 The attempt started; the binding view, in status pending.

application/json

Property	Type	Required	Description
`branch`	string	No	Target branch for this environment’s config.
Target branch for this environment’s config.
`display_name`	string	Yes	Human-readable repository name.
Human-readable repository name.
`git_repo_url`	string	Yes	HTTPS clone URL of the configuration repository.
HTTPS clone URL of the configuration repository.
`managed`	boolean	Yes	True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
`status`	RepoBindingStatus	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/restore`

Restore the environment's job graph to a committed ref.

Makes the environment’s whole job graph identical to the configuration committed at ref: jobs, their runs, their shared defaults and their per-object overrides, plus the contract documents those jobs reference, except their classification and PII-label state, which is carried over (see below). Within the configuration-import surface (this operation and the object-scoped import), this is the only one that removes a job or a run — a job absent at ref is deleted, and derived scheduling state keyed to it is deleted with it. Deleting a job outright is a separate, user-initiated operation (DELETE /v1/projects/{id}/jobs/{job_name}) that this restore never goes through. Never creates, alters or removes a source or target: a connection the staging area cannot resolve, or whose serialized attributes differ from ref, refuses the whole restore. Returns 409 when the committed config cannot be read back byte-for-byte, when a connection is unknown or diverged, or when ref carries job or run values the staging area cannot store. Generated documentation, dbt and SQL trees are not restored; they are reproduced by the next commit. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus), so a restored contract document takes the stored state by object and property identity (ClassificationStatus), whatever ref holds inline: an object or property the restore brings back gets its stored state again, and one the restore drops keeps its stored state. A history-mode change the restored configuration brings is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`ref`	string	Yes	Commit SHA to restore the job graph to. Required, and a commit SHA rather than a branch or tag name: a name that is not a well-formed hash is rejected the same way an absent commit is. Unlike the import request, an empty value is not accepted as “the branch tip” — this operation deletes jobs, so the tip must be named explicitly to be chosen.
Commit SHA to restore the job graph to. Required, and a commit SHA rather than a branch or tag name: a name that is not a well-formed hash is rejected the same way an absent commit is. Unlike the import request, an empty value is not accepted as “the branch tip” — this operation deletes jobs, so the tip must be named explicitly to be chosen.

Responses

200 The restore result.

application/json

Property	Type	Required	Description
`head_sha`	string	Yes	The branch tip at the time of the restore, which may be ahead of the restored ref.
The branch tip at the time of the restore, which may be ahead of the restored ref.
`reconciled_sha`	[string null]	No	The editing base after the restore. Unchanged by this operation; reported so a client need not re-read status.
The editing base after the restore. Unchanged by this operation; reported so a client need not re-read status.
`removed_jobs`	string[]	Yes	Names of jobs deleted because ref does not carry them, in sorted order. Their runs and any derived scheduling state were deleted with them.
Names of jobs deleted because ref does not carry them, in sorted order. Their runs and any derived scheduling state were deleted with them.
`restored_contracts`	string[]	Yes	Repo-relative paths of contract documents written, in sorted order.
Repo-relative paths of contract documents written, in sorted order.
`restored_jobs`	string[]	Yes	Names of jobs written, in sorted order.
Names of jobs written, in sorted order.
`restored_objects`	RepoImportObject []	Yes	The (job, object) pairs the restored graph selects, echoed so a client can confirm coverage.
The (job, object) pairs the restored graph selects, echoed so a client can confirm coverage.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/push`

Push agent-authored config files to Git (git-lite).

Commits caller-supplied config files to the environment’s connected Git repository via the control plane (ADR-066 §4). The agent supplies its own base_sha; a mismatch with the branch HEAD returns 409. While the project’s repository moves to the customer’s own (api#1090) the push waits: 409 with code repository_moving; when the repository changed between the read of the binding and the push, 409 with code repository_changed, and nothing is pushed.

It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus). The table classifications and PII labels inline in a pushed contract, proposed or approved, a property’s ODCS classification field included, are ignored, and the api commits the contract with the stored state in their place, by object and property identity (ClassificationStatus), as ingestCatalogContract stores a harvested contract. A history-mode change the pushed jobs bring is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves. A push answers no history_rebuild_required and takes no rebuild_history.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`base_sha`	string	Yes	The caller’s last-seen commit SHA. Empty on a first commit; a mismatch with the branch HEAD returns 409.
The caller’s last-seen commit SHA. Empty on a first commit; a mismatch with the branch HEAD returns 409.
`files`	ConfigFile []	Yes

Responses

200 The commit result.

application/json

Property	Type	Required	Description
`commit_sha`	string	Yes	The created commit SHA. Empty when the push was a no-op.
The created commit SHA. Empty when the push was a no-op.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/import`

Import committed configuration back into the staging area.

Makes the named objects in the staging area match the configuration committed at ref, adding, replacing or removing each object’s selection membership and override. Never creates or removes a source or target, and never removes a job or a run. Returns 409 when the committed config cannot be read as jobs and objects, or when a source or target it names is absent from or differs in the staging area. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus). A history-mode change the imported configuration brings is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`objects`	RepoImportObject []	Yes	The objects to make match ref. An object absent at ref is removed from the staging area.
The objects to make match ref. An object absent at ref is removed from the staging area.
`ref`	string	No	Commit SHA to import from. Omitted or empty means the branch tip, matching the repo tree read. A branch or tag name is not accepted.
Commit SHA to import from. Omitted or empty means the branch tip, matching the repo tree read. A branch or tag name is not accepted.

Responses

200 The import result.

application/json

Property	Type	Required	Description
`head_sha`	string	Yes	The branch tip at the time of the import, which may be ahead of ref.
The branch tip at the time of the import, which may be ahead of ref.
`imported_objects`	RepoImportObject []	Yes	The objects written, echoed back so a client can confirm what the import covered.
The objects written, echoed back so a client can confirm what the import covered.
`reconciled_sha`	[string null]	No	The editing base after the import. Unchanged by this operation; reported so a client need not re-read status.
The editing base after the import. Unchanged by this operation; reported so a client need not re-read status.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo/file`

Read one committed config file.

Returns one file’s content from the committed tree at ref (or at the branch tip when ref is omitted). A file larger than the server’s limit, or one that is not valid UTF-8, returns 200 with content omitted and unavailable_reason set — never a truncation. Returns 404 when no repo is bound or the path is not in the tree.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`path`	query	Yes	string	Repo-relative path, exactly as given on a RepoTreeEntry.
Repo-relative path, exactly as given on a RepoTreeEntry.
`ref`	query	No	string	Commit SHA to read the file at. Must resolve within the branch’s history. Omitted means the branch tip.
Commit SHA to read the file at. Must resolve within the branch’s history. Omitted means the branch tip.

Responses

200 The file, or a stated reason it cannot be shown.

application/json

Property	Type	Required	Description
`content`	string	No	The file’s verbatim UTF-8 content. Absent when unavailable_reason is set. Never truncated — a partial file a user cannot distinguish from the whole one is the outcome this field’s absence exists to prevent.
The file’s verbatim UTF-8 content. Absent when unavailable_reason is set. Never truncated — a partial file a user cannot distinguish from the whole one is the outcome this field’s absence exists to prevent.
`path`	string	Yes	Repo-relative path, echoing the request.
Repo-relative path, echoing the request.
`ref`	string	Yes	The commit the content was read at.
The commit the content was read at.
`size`	integer	Yes	Size in bytes.
Size in bytes.
`unavailable_reason`	string	No	Why content is absent. Absent itself when the file was returned. A client must render the reason rather than an empty file. Valid values are: `too_large`, `not_utf8`.
Why content is absent. Absent itself when the file was returned. A client must render the reason rather than an empty file. Valid values are: `too_large`, `not_utf8`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo/commits`

List commits on the bound branch.

Returns commits newest first, following FIRST PARENTS ONLY, starting at ref or at the branch tip when ref is omitted. A merge commit’s second parent and everything reachable only through it are excluded, so the result is this branch’s linear history. Returns 404 when no repo is bound.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`ref`	query	No	string	Commit SHA to anchor the walk at. Must resolve within the branch’s history. Omitted means the branch tip.
Commit SHA to anchor the walk at. Must resolve within the branch’s history. Omitted means the branch tip.
`limit`	query	No	integer	Maximum commits to return. Clamped to 200 rather than rejected, so a client asking for more receives the maximum instead of an error.
Maximum commits to return. Clamped to 200 rather than rejected, so a client asking for more receives the maximum instead of an error.

Responses

200 The commit list.

application/json

Property	Type	Required	Description
`commits`	RepoCommit []	Yes	One entry per commit. Empty when the branch has no commits yet.
One entry per commit. Empty when the branch has no commits yet.
`head_sha`	string	Yes	The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
`next_ref`	string	No	The commit to pass as ref to fetch the next page. ABSENT when the walk reached the root commit — which is how a client tells “this is the beginning” from “ask again”, without comparing counts to a limit it may not have set.
The commit to pass as ref to fetch the next page. ABSENT when the walk reached the root commit — which is how a client tells “this is the beginning” from “ask again”, without comparing counts to a limit it may not have set.
`ref`	string	Yes	The commit the walk started at. Echoed back so a client can pin a page and cache it — every page below the branch tip is immutable.
The commit the walk started at. Echoed back so a client can pin a page and cache it — every page below the branch tip is immutable.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo/commit/diff`

Read one commit's changes.

Returns the files ref changed relative to its first parent, as line-aligned diff rows. A file too large or not valid UTF-8 reports its reason and carries no rows, leaving the rest of the commit readable. Returns 404 when no repo is bound.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`ref`	query	Yes	string	Commit SHA to diff against its first parent. Must resolve within the branch’s history.
Commit SHA to diff against its first parent. Must resolve within the branch’s history.

Responses

200 The commit's changes.

application/json

Property	Type	Required	Description
`files`	RepoCommitDiffFile []	Yes	One entry per changed path. A path the commit did not touch is absent, never present with an empty row list.
One entry per changed path. A path the commit did not touch is absent, never present with an empty row list.
`parent_sha`	string	No	The first parent the diff was taken against. Absent at the root commit, where every path reads as added.
The first parent the diff was taken against. Absent at the root commit, where every path reads as added.
`ref`	string	Yes	The commit that was diffed.
The commit that was diffed.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/repo/commit`

Commit the environment's discovered contract(s) to Git.

Commits the environment’s discovered ODCS contract(s) to the configured Git repository. A non-fast-forward push rejection returns 409. A missing contract or binding returns 404. While the project’s repository moves to the customer’s own repository (api#1090), publishing waits: 409 with code repository_moving. When the project’s repository changed between the read of the binding and the push (a move finished meanwhile), nothing is pushed: 409 with code repository_changed. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus); the commit writes the stored contracts to the repository.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body

application/json

Property	Type	Required	Description
`base_sha`	string	No	The HEAD SHA the user reviewed against. When non-empty and it no longer matches the branch HEAD, the commit returns 409. When empty, the stored git_base_sha is used.
The HEAD SHA the user reviewed against. When non-empty and it no longer matches the branch HEAD, the commit returns 409. When empty, the stored git_base_sha is used.
`contracts`	string[]	No	Contract files to include, as repo-relative paths exactly as given on RepoStatusFile.path (e.g. “contracts/sales.odcs.yaml”). A contract is a whole-file unit (ADR-093 §6) — it commits entirely or not at all, never a subset of its content. Identified by path rather than by a job/name pair, because a contract belongs to a source rather than to an object. Omitted or empty commits no contract change, which is what an objects-only selection means; omitting BOTH objects and contracts is the whole-set commit.
Contract files to include, as repo-relative paths exactly as given on RepoStatusFile.path (e.g. “contracts/sales.odcs.yaml”). A contract is a whole-file unit (ADR-093 §6) — it commits entirely or not at all, never a subset of its content. Identified by path rather than by a job/name pair, because a contract belongs to a source rather than to an object. Omitted or empty commits no contract change, which is what an objects-only selection means; omitting BOTH objects and contracts is the whole-set commit.
`message`	string	No	Commit message. When blank, the control plane supplies a default.
Commit message. When blank, the control plane supplies a default.
`objects`	RepoObjectRef []	No	Objects to include, identified by job + name as given on each RepoStatusObject. Omitted or empty selects no object; omitting BOTH objects and contracts is the whole-set commit — the pre-existing behavior, so an older client is unaffected.
Objects to include, identified by job + name as given on each RepoStatusObject. Omitted or empty selects no object; omitting BOTH objects and contracts is the whole-set commit — the pre-existing behavior, so an older client is unaffected.

Responses

200 The commit result.

application/json

Property	Type	Required	Description
`commit_sha`	string	Yes	The created commit SHA. Empty when the commit was a no-op (no changes to push).
The created commit SHA. Empty when the commit was a no-op (no changes to push).
`files`	string[]	Yes	Repo-relative paths written by the commit.
Repo-relative paths written by the commit.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/repo`

Get the environment's Git repo binding.

Returns the non-secret view of the environment’s Git repository binding. The token is never returned. When the platform provisions the environment’s repository (ADR-129 decision 11) and it does not exist yet, the view has status pending or failed, managed true and an empty git_repo_url. 404 when the environment has no repository and none is being provisioned.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The environment's Git repo binding.

application/json

Property	Type	Required	Description
`branch`	string	No	Target branch for this environment’s config.
Target branch for this environment’s config.
`display_name`	string	Yes	Human-readable repository name.
Human-readable repository name.
`git_repo_url`	string	Yes	HTTPS clone URL of the configuration repository.
HTTPS clone URL of the configuration repository.
`managed`	boolean	Yes	True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
`status`	RepoBindingStatus	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/environments/{environment_id}/repo`

Connect or update the environment's Git repo binding.

Registers the repository URL + branch and stores the personal access token (PAT) write-only in the vault (ADR-056). Omit or blank the token on update to keep the existing one. Returns the non-secret binding view. Connecting a repository replaces a managed repository the platform provisioned (ADR-129 decision 11): the managed repository is detached, not deleted, and runs move to the new binding. Where the deployment provisions managed repositories, only an owner or admin (projects.update, on top of config.write) may connect or replace a repository: 403 otherwise.

It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus). Classification and PII-label state inline in the connected repository’s contract files is not taken into the control plane. A history-mode change that the connected repository’s configuration brings to the runs is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`branch`	string	No	Target branch for this environment’s config. Defaults to ‘main’ when omitted.
Target branch for this environment’s config. Defaults to ‘main’ when omitted.
`display_name`	string	Yes	Human-readable repository name.
Human-readable repository name.
`git_repo_url`	string	Yes	HTTPS clone URL of the configuration repository.
HTTPS clone URL of the configuration repository.
`token`	string	No	Personal access token (PAT) for git-over-HTTPS. Write-only; omit or send blank to keep the existing token (ADR-056 merge rule). Never returned on read.
Personal access token (PAT) for git-over-HTTPS. Write-only; omit or send blank to keep the existing token (ADR-056 merge rule). Never returned on read.

Responses

200 The updated Git repo binding.

application/json

Property	Type	Required	Description
`branch`	string	No	Target branch for this environment’s config.
Target branch for this environment’s config.
`display_name`	string	Yes	Human-readable repository name.
Human-readable repository name.
`git_repo_url`	string	Yes	HTTPS clone URL of the configuration repository.
HTTPS clone URL of the configuration repository.
`managed`	boolean	Yes	True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
`status`	RepoBindingStatus	Yes

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources`

List a project environment's catalog sources.

Returns the discovered catalog sources (and target) for the project + environment — id, name, description, role, plugin. Backed by the interim ODCS-contract store (ADR-060).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The environment's catalog sources.

application/json

Property	Type	Required	Description
`data`	CatalogSource []	Yes	The catalog sources.
The catalog sources.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/doc-notes`

Get the authored prose on one catalog page.

Returns the protected-region prose a customer authored in their configuration repository for one catalog page, projected to the control plane at commit time so no git read is needed to display it. Addressed by catalog coordinate rather than by the page’s emitted path, because reproducing that path needs the documentation root from the project’s PCF. A page with no prose, or a project with documentation disabled, returns an empty list rather than an error.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`page_kind`	query	Yes	string (enum: `project`, `entity`, `namespace`, `object`)	Which sort of documentation page to read. The discriminator that makes the coordinates below unambiguous: an empty namespace on an object page is the genuine unnamespaced bucket, where on an entity page it means the parameter does not apply.
Which sort of documentation page to read. The discriminator that makes the coordinates below unambiguous: an empty namespace on an object page is the genuine unnamespaced bucket, where on an entity page it means the parameter does not apply.
`entity_role`	query	No	string	Catalog role of the source or target — “source” or “target”. Omitted for page_kind=project. Deliberately not declared as an enum: oapi-codegen emits enum constants unprefixed while their names are globally unique and prefixes every member once two enums collide, so a “source” member here would rename the pre-existing exported GetPluginByNameParamsCategory constants in the generated client. That is a breaking change to published consumers in exchange for documentation this description already carries.
Catalog role of the source or target — “source” or “target”. Omitted for page_kind=project. Deliberately not declared as an enum: oapi-codegen emits enum constants unprefixed while their names are globally unique and prefixes every member once two enums collide, so a “source” member here would rename the pre-existing exported GetPluginByNameParamsCategory constants in the generated client. That is a breaking change to published consumers in exchange for documentation this description already carries.
`entity_slug`	query	No	string	Catalog slug of the source or target. Omitted for page_kind=project.
Catalog slug of the source or target. Omitted for page_kind=project.
`namespace`	query	No	string	Namespace name. Omitted for page_kind=project and page_kind=entity.
Namespace name. Omitted for page_kind=project and page_kind=entity.
`object`	query	No	string	Object name. Supplied only for page_kind=object.
Object name. Supplied only for page_kind=object.

Responses

200 The page's authored prose, empty when there is none.

application/json

Property	Type	Required	Description
`notes`	DocNote []	Yes	One entry per protected region on the page, ordered by region name. Empty when the page carries no prose, when the project has documentation disabled, or when nothing has been committed yet — all three render identically, as nothing.
One entry per protected region on the page, ordered by region name. Empty when the page carries no prose, when the project has documentation disabled, or when nothing has been committed yet — all three render identically, as nothing.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/environments/{environment_id}/agent`

Assign the agent that executes one project environment.

Binds an agent to one of the project’s environments (exec.project_environment.agent_id, ADR-160 decision 9). Runs, deploys and connection tests for that environment dispatch to this agent. The agent must be active and belong to the same tenant. It may serve other environments, of this or other projects, as well.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	The DTAP environment slug.
The DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`agent_id`	string	Yes	The agent to pin as the executing agent — must be an active agent in the same tenant.
The agent to pin as the executing agent — must be an active agent in the same tenant.

Responses

200 The project environment with the assigned agent.

application/json

Property	Type	Required	Description
`agent_commit_reported_at`	[string null]	No	When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
`agent_commit_sha`	[string null]	No	Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`agent_id`	[string null]	No	The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
`deployed_commit_sha`	[string null]	No	Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`environment_id`	string	Yes	The DTAP environment slug.
The DTAP environment slug.
`id`	string	Yes	Binding identifier.
Binding identifier.
`name`	string	Yes	Environment display name.
Environment display name.
`project_id`	string	Yes	The project.
The project.
`sort_order`	integer	Yes	DTAP promotion order (ascending).
DTAP promotion order (ascending).

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

422 The request was well-formed but failed semantic validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/environments/{environment_id}/agent`

Clear the agent that executes one project environment.

Removes the agent bound to one of the project’s environments, setting exec.project_environment.agent_id to null. The project’s other environments keep their agents.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	The DTAP environment slug.
The DTAP environment slug.

Responses

200 The project environment with the agent cleared.

application/json

Property	Type	Required	Description
`agent_commit_reported_at`	[string null]	No	When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
`agent_commit_sha`	[string null]	No	Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`agent_id`	[string null]	No	The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
`deployed_commit_sha`	[string null]	No	Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`environment_id`	string	Yes	The DTAP environment slug.
The DTAP environment slug.
`id`	string	Yes	Binding identifier.
Binding identifier.
`name`	string	Yes	Environment display name.
Environment display name.
`project_id`	string	Yes	The project.
The project.
`sort_order`	integer	Yes	DTAP promotion order (ascending).
DTAP promotion order (ascending).

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

DELETE `/v1/projects/{id}/environments/{environment_id}`

Unbind a project environment.

Removes a DTAP slot from the project. The last remaining environment cannot be removed.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	The DTAP environment slug.
The DTAP environment slug.

Responses

204 The environment was unbound.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/jobs/{job_name}/runs/{run_name}/resume`

Resume one paused schedule of a job.

Resumes one paused scheduled entry of a job in one environment: the pause fields clear and next_run_at is computed from the time of the resume. Fires missed while paused are not replayed. It applies to the named environment only. Every resume that changes the state writes one audit event (object type schedule, action update). The operation is idempotent: resuming an entry that is not paused returns 200 with the unchanged state and writes no audit event.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`job_name`	path	Yes	string	Job name.
Job name.
`run_name`	path	Yes	string	Name of the scheduled entry within the job, the run_name of its ScheduleState.
Name of the scheduled entry within the job, the run_name of its ScheduleState.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Responses

200 The schedule state of the entry after the request.

application/json

Property	Type	Required	Description
`job_name`	string	Yes	Name of the job the schedule belongs to. Examples: `orders_nightly`.
Name of the job the schedule belongs to. Examples: `orders_nightly`.
`last_fired_at`	[string null]	No	When the control plane last dispatched this entry. Always present on the wire; null means no dispatch is currently recorded for it. Examples: `2026-09-16T03:00:00Z`.
When the control plane last dispatched this entry. Always present on the wire; null means no dispatch is currently recorded for it. Examples: `2026-09-16T03:00:00Z`.
`next_run_at`	[string null]	No	The control plane’s computed next fire for this entry. Always present on the wire; null means no next fire is currently known, which is not the same as the entry having no schedule at all — an entry with no schedule is absent from this list rather than present with a null timestamp. It is null while the entry is paused; on resume it is computed from the time of the resume. It is an instant; a client shows it in the project’s time_zone, which the project read carries. Examples: `2026-09-17T03:00:00Z`.
The control plane’s computed next fire for this entry. Always present on the wire; null means no next fire is currently known, which is not the same as the entry having no schedule at all — an entry with no schedule is absent from this list rather than present with a null timestamp. It is null while the entry is paused; on resume it is computed from the time of the resume. It is an instant; a client shows it in the project’s time_zone, which the project read carries. Examples: `2026-09-17T03:00:00Z`.
`pause_reason`	[string null]	No	The reason the operator gave when pausing the entry. Always present on the wire; null while the entry is not paused. Examples: `source maintenance`.
The reason the operator gave when pausing the entry. Always present on the wire; null while the entry is not paused. Examples: `source maintenance`.
`paused`	boolean	Yes	Whether an operator paused this entry (pauseJobSchedule). A paused entry starts no new run until it is resumed. Pause is operational state set by an operator, not part of the job document. Examples: `false`.
Whether an operator paused this entry (pauseJobSchedule). A paused entry starts no new run until it is resumed. Pause is operational state set by an operator, not part of the job document. Examples: `false`.
`paused_at`	[string null]	No	When the entry was paused. Always present on the wire; null while the entry is not paused. Examples: `2026-10-09T08:00:00Z`.
When the entry was paused. Always present on the wire; null while the entry is not paused. Examples: `2026-10-09T08:00:00Z`.
`paused_by`		No	The account that paused the entry. Always present on the wire; null while the entry is not paused.
The account that paused the entry. Always present on the wire; null while the entry is not paused.
`run_name`	string	Yes	Name of the scheduled entry within the job. Matches the name of the corresponding entry in the job document’s runs list, which is the join key between the two payloads. Examples: `nightly`.
Name of the scheduled entry within the job. Matches the name of the corresponding entry in the job document’s runs list, which is the join key between the two payloads. Examples: `nightly`.
`schedule`	string	Yes	The cron expression as authored on the job, evaluated in the project’s time_zone. The control plane maintains its own scheduling state from this value, so next_run_at and last_fired_at may trail an edit to it. Examples: `0 3 * * *`.
The cron expression as authored on the job, evaluated in the project’s time_zone. The control plane maintains its own scheduling state from this value, so next_run_at and last_fired_at may trail an edit to it. Examples: `0 3 * * *`.

400 Code invalid_argument: the environment query parameter is missing or empty. Nothing changes.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 Code not_found: the project does not exist, the environment does not exist in the project, or the job named by job_name or its entry named by run_name does not exist in the environment. Nothing changes.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The entry cannot be resumed in its current state. Nothing changes. The causes are: the entry exists but carries no cron expression, so this run has no schedule (code conflict); the entry carries a cron expression but the scheduler has not yet picked it up, for example a run added to the job since the scheduler's last pass, answered with "this schedule is not active yet; retry shortly" (code conflict); the project is archived (code project_archived).

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/jobs/{job_name}/runs/{run_name}/pause`

Pause one schedule of a job.

Pauses one scheduled entry of a job in one environment: the scheduler starts no new run of the entry until it is resumed, and next_run_at reads null meanwhile. A run already in flight is not cancelled. Pause is operational control-plane state, not a change to the job document, so it needs no commit or promotion, survives an edit of the job or its cron, and is removed together with the entry. It applies to the named environment only. Every pause that changes the state writes one audit event (object type schedule, action update). The operation is idempotent: pausing an entry that is already paused returns 200 with the unchanged state, keeps the original paused_at, paused_by and pause_reason, and writes no audit event.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`job_name`	path	Yes	string	Job name.
Job name.
`run_name`	path	Yes	string	Name of the scheduled entry within the job, the run_name of its ScheduleState.
Name of the scheduled entry within the job, the run_name of its ScheduleState.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.

Request body (required)

application/json

Property	Type	Required	Description
`reason`	string	Yes	Why the entry is paused, shown with the paused state. Examples: `source maintenance`.
Why the entry is paused, shown with the paused state. Examples: `source maintenance`.

Responses

200 The schedule state of the entry after the request.

application/json

Property	Type	Required	Description
`job_name`	string	Yes	Name of the job the schedule belongs to. Examples: `orders_nightly`.
Name of the job the schedule belongs to. Examples: `orders_nightly`.
`last_fired_at`	[string null]	No	When the control plane last dispatched this entry. Always present on the wire; null means no dispatch is currently recorded for it. Examples: `2026-09-16T03:00:00Z`.
When the control plane last dispatched this entry. Always present on the wire; null means no dispatch is currently recorded for it. Examples: `2026-09-16T03:00:00Z`.
`next_run_at`	[string null]	No	The control plane’s computed next fire for this entry. Always present on the wire; null means no next fire is currently known, which is not the same as the entry having no schedule at all — an entry with no schedule is absent from this list rather than present with a null timestamp. It is null while the entry is paused; on resume it is computed from the time of the resume. It is an instant; a client shows it in the project’s time_zone, which the project read carries. Examples: `2026-09-17T03:00:00Z`.
The control plane’s computed next fire for this entry. Always present on the wire; null means no next fire is currently known, which is not the same as the entry having no schedule at all — an entry with no schedule is absent from this list rather than present with a null timestamp. It is null while the entry is paused; on resume it is computed from the time of the resume. It is an instant; a client shows it in the project’s time_zone, which the project read carries. Examples: `2026-09-17T03:00:00Z`.
`pause_reason`	[string null]	No	The reason the operator gave when pausing the entry. Always present on the wire; null while the entry is not paused. Examples: `source maintenance`.
The reason the operator gave when pausing the entry. Always present on the wire; null while the entry is not paused. Examples: `source maintenance`.
`paused`	boolean	Yes	Whether an operator paused this entry (pauseJobSchedule). A paused entry starts no new run until it is resumed. Pause is operational state set by an operator, not part of the job document. Examples: `false`.
Whether an operator paused this entry (pauseJobSchedule). A paused entry starts no new run until it is resumed. Pause is operational state set by an operator, not part of the job document. Examples: `false`.
`paused_at`	[string null]	No	When the entry was paused. Always present on the wire; null while the entry is not paused. Examples: `2026-10-09T08:00:00Z`.
When the entry was paused. Always present on the wire; null while the entry is not paused. Examples: `2026-10-09T08:00:00Z`.
`paused_by`		No	The account that paused the entry. Always present on the wire; null while the entry is not paused.
The account that paused the entry. Always present on the wire; null while the entry is not paused.
`run_name`	string	Yes	Name of the scheduled entry within the job. Matches the name of the corresponding entry in the job document’s runs list, which is the join key between the two payloads. Examples: `nightly`.
Name of the scheduled entry within the job. Matches the name of the corresponding entry in the job document’s runs list, which is the join key between the two payloads. Examples: `nightly`.
`schedule`	string	Yes	The cron expression as authored on the job, evaluated in the project’s time_zone. The control plane maintains its own scheduling state from this value, so next_run_at and last_fired_at may trail an edit to it. Examples: `0 3 * * *`.
The cron expression as authored on the job, evaluated in the project’s time_zone. The control plane maintains its own scheduling state from this value, so next_run_at and last_fired_at may trail an edit to it. Examples: `0 3 * * *`.

400 Code invalid_argument: the environment query parameter is missing or empty, the body is malformed, or reason is missing, empty, or longer than 200 characters. Nothing changes.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The entry cannot be paused in its current state. Nothing changes. The causes are: the entry exists but carries no cron expression, so this run has no schedule (code conflict); the entry carries a cron expression but the scheduler has not yet picked it up, for example a run added to the job since the scheduler's last pass, answered with "this schedule is not active yet; retry shortly" (code conflict); the project is archived (code project_archived).

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/object-advice`

List a catalog source's object-level advice recommendations.

Returns the LLM advisor’s recommended table type per object, as stored via the agent-harvest ingest endpoint (ADR-092).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

200 The source's object-level advice recommendations.

application/json

Property	Type	Required	Description
`data`	ObjectAdvice []	Yes	The object-level advice recommendations.
The object-level advice recommendations.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/history-rebuilds`

List a catalog source's pending history rebuilds.

The app’s read of the source’s pending history rebuilds, per object and target: exactly the rebuilds of the source whose status is pending, at most one per object and target, oldest requested_at first, and an empty data when there are none. A completed or canceled rebuild is never returned. It lists an object’s pending rebuild whether or not the object has a classification (a job’s history-mode override can need one too), so an object without one still shows it; ObjectClassification.history_rebuilds lists the same rebuilds for a classified object. Read like listProjectCatalogClassifications.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

200 The source's pending history rebuilds; empty when there are none.

application/json

Property	Type	Required	Description
`data`	HistoryRebuild []	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/drift-events`

List schema-drift events for a catalog source.

Returns recorded source schema-drift events (CAP-01-03) for the source, newest first. Each event carries the rolled-up semver bump and the full drift record.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`limit`	query	No	integer	Maximum number of events to return (default 50).
Maximum number of events to return (default 50).
`offset`	query	No	integer	Number of events to skip (default 0).
Number of events to skip (default 0).

Responses

200 Schema-drift events, newest first.

application/json

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/discover`

Trigger a live schema harvest for a catalog source.

Dispatches cmd.import to the source’s assigned agent over the icpc channel; the agent harvests the ODCS contract and writes it back via the agent-auth ingest endpoint (ADR-063). Returns the dispatch command id for correlation. The discover is recorded on the source. When it finishes done for a source with no job, onboarding creates the first job (see first_job on the source read), and for a source with an automatic discover, auto_discover then describes this discover. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus), since the harvested contract is written through ingestCatalogContract.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

202 Harvest dispatched.

application/json

Property	Type	Required	Description
`command_id`	string	Yes	The dispatched command id, for correlating run events.
The dispatched command id, for correlating run events.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/contract`

Get a catalog source's ODCS contract.

Returns the discovered ODCS v3 data contract for the source, verbatim, as contract_yaml. The app parses it client-side (ADR-060).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

200 The source's ODCS contract.

application/json

Property	Type	Required	Description
`contract_yaml`	string	Yes	The ODCS v3 contract document, verbatim YAML.
The ODCS v3 contract document, verbatim YAML.
`created_at`	string	Yes	Timestamp the contract document was first harvested.
Timestamp the contract document was first harvested.
`updated_at`	string	Yes	Timestamp the contract document was last re-harvested; every metadata ingest bumps it, so the app can detect re-discovery completion and show a DB-accurate last-discovery time.
Timestamp the contract document was last re-harvested; every metadata ingest bumps it, so the app can detect re-discovery completion and show a DB-accurate last-discovery time.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

PUT `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/contract`

Upsert a catalog source's ODCS contract.

Stores the discovered ODCS contract plus its denormalized list fields, keyed by project + environment + source slug: the seed seam (ADR-060). The agent harvest writes through ingestCatalogContract.

It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus). The table classifications and PII labels inline in contract_yaml, proposed or approved, a property’s ODCS classification field included, are ignored; the stored revision takes the stored state by object and property identity (ClassificationStatus), so an object or property this write drops keeps its stored state and gets it back when a later write brings it back, and one with no stored state has none. So a catalog.write caller cannot approve a classification or a label through it (api#1247), and it changes no object’s classification or history mode. It answers no history_rebuild_required and takes no rebuild_history: history is covered by the run-time refusal (HistoryRebuildConflict), not by a 409, for an object whose built mode is recorded; one with no record adopts the mode its run resolves.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Request body (required)

application/json

Property	Type	Required	Description
`contract_yaml`	string	Yes	The ODCS v3 contract document, verbatim YAML.
The ODCS v3 contract document, verbatim YAML.
`description`	string	No	Short description.
Short description.
`name`	string	No	Source display name.
Source display name.
`plugin`	string	No

`role`	string	No	Valid values are: `source`, `target`.
Valid values are: `source`, `target`.

Responses

200 The upserted contract source.

application/json

Property	Type	Required	Description
`description`	string	No	Short description.
Short description.
`id`	string	Yes	Catalog source slug.
Catalog source slug.
`name`	string	Yes	Source display name.
Source display name.
`plugin`	string	No	Plugin key (e.g. postgres, snowflake).
Plugin key (e.g. postgres, snowflake).
`role`	string	Yes	Whether the asset is an inbound source or the outbound target. Valid values are: `source`, `target`.
Whether the asset is an inbound source or the outbound target. Valid values are: `source`, `target`.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/classifications`

List a catalog source's table classifications and PII labels.

Returns every table classification and PII label the source’s contract carries, proposed or approved, with confidence, method and who approved it (ADR-159, Decision 4). Objects and properties without one are left out.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

200 The source's classifications and PII labels.

application/json

Property	Type	Required
`objects`	ObjectClassification []	Yes

`pii`	PiiLabel []	Yes

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/advise`

Trigger LLM-backed object-type advice for a catalog source.

Dispatches cmd.advise to the source’s assigned agent over the icpc channel; the agent requests object-type table-type recommendations from the LLM advisor and writes them back via the agent-auth ingest endpoint (ADR-092). Returns the dispatch command id for correlation. It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus), since the recommendations are written through ingestObjectAdvice.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

202 Advice dispatched.

application/json

Property	Type	Required	Description
`command_id`	string	Yes	The dispatched command id, for correlating run events.
The dispatched command id, for correlating run events.

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/activity`

Get what a catalog source's objects have landed in the warehouse.

Returns, per catalog object, what the runs actually did: the most recent load (per object, not per source), its per-layer row counts and durations, and lifetime totals across every run. Sourced from the run domain (exec.run / exec.task) — these are run activity, NOT current warehouse table state. An object with no recorded task is absent from the response; the caller renders it as “never loaded” rather than inventing an empty record.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.

Responses

200 Per-object load activity for the source.

application/json

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/profiles/latest`

Get the latest profile of one schema object.

Returns the most recent profile of the object with its body: row count and per-column statistics, signals, PII evidence and the proposed PII verdicts.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).

Responses

200 The object's latest profile.

application/json

Child elements:

CatalogProfileSummary

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

GET `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/profiles`

List the profiles of one schema object.

Returns the profiles the agent took of the object (ADR-159, Decision 3), newest first by when the load they were taken from landed, without their bodies.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).
`limit`	query	No	integer	The maximum number of profiles to return, newest first.
The maximum number of profiles to return, newest first.

Responses

200 The object's profiles, newest first.

application/json

Property	Type	Required	Description
`data`	CatalogProfileSummary []	Yes

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/classification/reject`

Reject a schema object's proposed table classification.

Removes the object’s proposed table classification from the contract and stores it as a new revision. Answers 409 when there is no proposal or it is already approved: an approved classification cannot be rejected. It is one of the operations that own classification state (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).

Responses

204 The proposal was removed.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/classification/approve`

Approve a schema object's proposed table classification.

Marks the object’s proposed table classification as approved by the caller and stores the contract as a new revision. Fields in the body replace the proposed values before approval. An approved classification decides, when no job override sets one (an explicit historyMode, ADR-068), the object’s history mode, how its history rows are written, and is never replaced by a later proposal. Answers 409 when there is no proposal or it is already approved (code conflict; change an approved one with changeProjectCatalogObjectClassification), and 409 history_rebuild_required when the approval would change the history mode of an object whose history already exists on a target and the body does not set rebuild_history; confirmed, it records a pending history rebuild of the object on each such target for its next run (HistoryRebuildConflict). It is one of the operations that own classification state (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).

Request body

application/json

Property	Type	Required	Description
`business_key`	string[]	No

`history_mode`	string	No

`rebuild_history`	boolean	No	Confirms that a history-mode change may drop the history the object already has on a target; the next run rebuilds it from current staging in the new mode. Without it, such a change answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when the history mode does not change or the object has no history yet.
Confirms that a history-mode change may drop the history the object already has on a target; the next run rebuilds it from current staging in the new mode. Without it, such a change answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when the history mode does not change or the object has no history yet.
`table_type`	string	No

`transactional`	boolean	No

Responses

200 The approved classification.

application/json

Property	Type	Required	Description
`approved_at`	string	No	When the classification was approved, or last changed: a change (changeProjectCatalogObjectClassification) records its own time.
When the classification was approved, or last changed: a change (changeProjectCatalogObjectClassification) records its own time.
`approved_by`	string	No	Who approved the classification, or last changed it: the person who approved it (approveProjectCatalogObjectClassification) or changed it (changeProjectCatalogObjectClassification), or the literal advisor for an auto-approval verified against the advisor call it names (ingestCatalogClassifications). No other write sets it (ClassificationStatus). An auto-applied classification can be changed like any approved one; the change applies from the next run.
Who approved the classification, or last changed it: the person who approved it (approveProjectCatalogObjectClassification) or changed it (changeProjectCatalogObjectClassification), or the literal advisor for an auto-approval verified against the advisor call it names (ingestCatalogClassifications). No other write sets it (ClassificationStatus). An auto-applied classification can be changed like any approved one; the change applies from the next run.
`business_key`	string[]	No

`confidence`	number	No

`history_mode`	string	No

`history_rebuilds`	HistoryRebuild []	No	The object’s pending history rebuilds, at most one per target; empty or absent when none is pending. A completed or canceled rebuild is not listed.
The object’s pending history rebuilds, at most one per target; empty or absent when none is pending. A completed or canceled rebuild is not listed.
`object_name`	string	Yes

`proposed_at`	string	No

`proposed_by`	string	No

`status`	ClassificationStatus	Yes

`table_type`	string	Yes

`transactional`	boolean	Yes

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 Code conflict: there is no proposal, or it is already approved. Code history_rebuild_required: the approval would change the history mode of an object whose history already exists on a target; objects names it per target. Nothing is changed.

application/json

Property	Type	Required	Description
`code`	string	Yes	As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	HistoryModeChange []	No	Set with code history_rebuild_required; the objects the change would rebuild.
Set with code history_rebuild_required; the objects the change would rebuild.

Security

bearer_jwt

PUT `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/classification`

Change a schema object's approved table classification.

Replaces values of the object’s approved table classification, whether a person approved it or the advisor applied it, records the caller as approved_by and the time of the change as approved_at, and stores the contract as a new revision. It is one of the operations that own classification state (ClassificationStatus). The change applies from the next run. A change of history mode on an object whose history already exists on a target drops that history, so it answers 409 history_rebuild_required unless the body sets rebuild_history; confirmed, it records a pending history rebuild of the object on each such target for its next run (HistoryRebuildConflict). Answers 409 (code conflict) when the object has no approved classification: approve a proposal with approveProjectCatalogObjectClassification.

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).

Request body (required)

application/json

Property	Type	Required	Description
`business_key`	string[]	No

`history_mode`	string	No

`rebuild_history`	boolean	No	Confirms that a history-mode change may drop the history the object already has on a target; the next run rebuilds it from current staging in the new mode. Without it, such a change answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when the history mode does not change or the object has no history yet.
Confirms that a history-mode change may drop the history the object already has on a target; the next run rebuilds it from current staging in the new mode. Without it, such a change answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when the history mode does not change or the object has no history yet.
`table_type`	string	No

`transactional`	boolean	No

Responses

200 The changed classification.

application/json

Property	Type	Required	Description
`approved_at`	string	No	When the classification was approved, or last changed: a change (changeProjectCatalogObjectClassification) records its own time.
When the classification was approved, or last changed: a change (changeProjectCatalogObjectClassification) records its own time.
`approved_by`	string	No	Who approved the classification, or last changed it: the person who approved it (approveProjectCatalogObjectClassification) or changed it (changeProjectCatalogObjectClassification), or the literal advisor for an auto-approval verified against the advisor call it names (ingestCatalogClassifications). No other write sets it (ClassificationStatus). An auto-applied classification can be changed like any approved one; the change applies from the next run.
Who approved the classification, or last changed it: the person who approved it (approveProjectCatalogObjectClassification) or changed it (changeProjectCatalogObjectClassification), or the literal advisor for an auto-approval verified against the advisor call it names (ingestCatalogClassifications). No other write sets it (ClassificationStatus). An auto-applied classification can be changed like any approved one; the change applies from the next run.
`business_key`	string[]	No

`confidence`	number	No

`history_mode`	string	No

`history_rebuilds`	HistoryRebuild []	No	The object’s pending history rebuilds, at most one per target; empty or absent when none is pending. A completed or canceled rebuild is not listed.
The object’s pending history rebuilds, at most one per target; empty or absent when none is pending. A completed or canceled rebuild is not listed.
`object_name`	string	Yes

`proposed_at`	string	No

`proposed_by`	string	No

`status`	ClassificationStatus	Yes

`table_type`	string	Yes

`transactional`	boolean	Yes

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 Code conflict: the object has no approved classification. Code history_rebuild_required: the change would change the history mode of an object whose history already exists on a target; objects names it per target. Nothing is changed.

application/json

Property	Type	Required	Description
`code`	string	Yes	As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	HistoryModeChange []	No	Set with code history_rebuild_required; the objects the change would rebuild.
Set with code history_rebuild_required; the objects the change would rebuild.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/properties/{property_name}/pii/reject`

Reject a property's proposed PII label.

Removes the property’s proposed PII label from the contract and stores it as a new revision. Answers 409 when there is no proposal or it is already approved. It is one of the operations that own classification state (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).
`property_name`	path	Yes	string	The property’s ODCS name (schema[].properties[].name).
The property’s ODCS name (schema[].properties[].name).

Responses

204 The proposal was removed.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

POST `/v1/projects/{id}/environments/{environment_id}/catalog/sources/{source_slug}/objects/{object_name}/properties/{property_name}/pii/approve`

Approve a property's proposed PII label.

Marks the property’s proposed PII label as approved by the caller, sets the property’s ODCS classification field to the given sensitivity, and stores the contract as a new revision. A label in the body replaces the proposed one before approval. Answers 409 when there is no proposal or it is already approved. It is one of the operations that own classification state (ClassificationStatus).

Parameters

Name	In	Required	Type	Description
`id`	path	Yes	string	Project identifier.
Project identifier.
`environment_id`	path	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	path	Yes	string	Catalog source slug.
Catalog source slug.
`object_name`	path	Yes	string	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).
`property_name`	path	Yes	string	The property’s ODCS name (schema[].properties[].name).
The property’s ODCS name (schema[].properties[].name).

Request body (required)

application/json

Property	Type	Required	Description
`classification`	string	Yes	The ODCS classification to set on the property, for example restricted or confidential.
The ODCS classification to set on the property, for example restricted or confidential.
`label`	string	No	A label that replaces the proposed one before approval.
A label that replaces the proposed one before approval.

Responses

200 The approved label.

application/json

Property	Type	Required	Description
`approved_at`	string	No

`approved_by`	string	No

`classification`	string	No	The property’s ODCS classification field, set on approval.
The property’s ODCS classification field, set on approval.
`confidence`	number	Yes

`label`	string	Yes

`method`	string	Yes

`object_name`	string	Yes

`property_name`	string	Yes

`proposed_at`	string	Yes

`status`	ClassificationStatus	Yes

400 The request was malformed or failed validation.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

401 The request lacks valid credentials.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

403 The caller is authenticated but not permitted to perform the request.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

404 The specified resource was not found.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

409 The request conflicts with the current state of the resource.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Security

bearer_jwt

Schemas

Table Type List

type: TableTypeList

Property	Type	Required	Description
`data`	TableType []	Yes

Table Type

type: TableType

Property	Type	Required	Description
`history_mode`	string	Yes	The history mode this classification derives when no explicit historyMode is set. Examples: `scd2`.
The history mode this classification derives when no explicit historyMode is set. Examples: `scd2`.
`table_type`	string	Yes	The business classification of a table. Examples: `master`.
The business classification of a table. Examples: `master`.

Error

type: Error

The standard error envelope returned by every non-2xx response.

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of the error. Examples: `limit must be between 1 and 100`.
Human-readable description of the error. Examples: `limit must be between 1 and 100`.

Project List

type: ProjectList

The tenant’s projects.

Property	Type	Required	Description
`data`	Project []	Yes	The projects.
The projects.

Project

type: Project

A project within a tenant.

Property	Type	Required	Description
`agent_display_name`	[string null]	No	Display name of the pinned agent, denormalized for the UI.
Display name of the pinned agent, denormalized for the UI.
`agent_id`	[string null]	No	The project’s pinned executing agent; null when none is assigned.
The project’s pinned executing agent; null when none is assigned.
`archived_at`	[string null]	No	When the project was disabled (archived); null when active.
When the project was disabled (archived); null when active.
`created_at`	string	Yes	Timestamp the project was created.
Timestamp the project was created.
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`id`	string	Yes	Unique identifier of the project.
Unique identifier of the project.
`status`	string	No	Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
Evidence-backed aggregate status (ADR-098). One of archived, failing, error, unconfigured, configured, verified, active — the worst state across the project’s sources and platforms (failing > error > unconfigured > configured > verified > active), except archived, which sits above that ladder entirely: a lifecycle fact evidenced by archived_at, not a run or a config row. A project with no sources and no platforms is configured, not unconfigured — there is no child status to derive from, so the project’s own existence stands as the evidence. Derived per request and never stored. Populated on the project read paths (list and get); absent on write responses, where absence means no derived status was computed here — never a state in itself.
`status_evidence_at`	string	No	Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
Timestamp of the evidence behind status: archived_at when status is archived, the project’s own created_at when it has no sources and no platforms, otherwise the evidence timestamp of whichever child produced the worst status. Populated on the project read paths (list and get); absent on write responses. A consumer must treat absence as “no derived status available here” and fall back, never as a state in itself.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`tenant_id`	string	Yes	Identifier of the owning tenant.
Identifier of the owning tenant.
`time_zone`	string	Yes	The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. A project created without one, and a project that existed before projects had a time zone, has “UTC”. Schedules compute their next run in this zone: a cron expression is evaluated in it. Examples: `Europe/Amsterdam`.

Project Create

type: ProjectCreate

The payload for creating a project.

Property	Type	Required	Description
`display_name`	string	Yes	Human-readable name of the project.
Human-readable name of the project.
`environments`	string[]	No	Initial DTAP environment slugs to bind (defaults to [“development”] when omitted).
Initial DTAP environment slugs to bind (defaults to [“development”] when omitted).
`time_zone`	string	No	The project’s IANA time zone name. The app sends the creating user’s browser time zone. Omitted, the project gets “UTC”. Examples: `Europe/Amsterdam`.
The project’s IANA time zone name. The app sends the creating user’s browser time zone. Omitted, the project gets “UTC”. Examples: `Europe/Amsterdam`.

Environment List

type: EnvironmentList

The DTAP environment lookup.

Property	Type	Required	Description
`data`	Environment []	Yes

Environment

type: Environment

A DTAP environment from the lookup.

Property	Type	Required	Description
`id`	string	Yes	Slug: development \| test \| acceptance \| production.
Slug: development \| test \| acceptance \| production.
`name`	string	Yes	Display name.
Display name.
`sort_order`	integer	Yes	DTAP promotion order (ascending).
DTAP promotion order (ascending).

Project Source List

type: ProjectSourceList

A list of a project’s data-source connections.

Property	Type	Required	Description
`data`	ProjectSource []	Yes	The data sources.
The data sources.

Project Source

type: ProjectSource

A project’s data-source connection (non-secret view). The stored secret is never returned. The latest connection test, failures included, is in last_test.

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`auto_discover`		No	The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
The discover onboarding started by itself after a passing connection test of this source, or the later discover a user started for the same source. Always present on the wire; null means onboarding did nothing automatic for this source.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, database, schema). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`first_job`		No	The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
The job onboarding created, or tried to create, for this source after its first discover finished. Always present on the wire; null means onboarding did nothing automatic for this source, for example because the source already had a job, or its discover has not finished or found no table.
`id`	string	Yes	Data source identifier.
Data source identifier.
`last_test`	LastConnectionTest	No

`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, failing, error. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest terminal run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active when it succeeded and failing when it failed. A passing test that is newer makes it verified. A failing test that is newer makes it configured, never failing, which stays reserved for runs, with the failure’s result code and message in last_test; a later run, succeeded or failed, takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the source’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active or failing when a terminal run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active/failing; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.
`updated_at`	string	Yes	When the data source’s configuration last changed. Recording a connection test does not move it.
When the data source’s configuration last changed. Recording a connection test does not move it.

Source Auto Discover

type: SourceAutoDiscover

The schema discovery (cmd.import) onboarding dispatched for a data source after its connection test passed, without a Discover request. Onboarding dispatches it only for a source that has had no done discover finding a table, judged by the source’s own history: a source deleted and created again with the same slug starts afresh, whatever catalog contract remains, and a source created before onboarding existed gets no automatic discover. At most one runs at a time: a passing test while a discover is pending or done dispatches nothing, and a passing test after a failed discover dispatches one new discover. A discover a user starts for the same source replaces it, and this object then describes that discover, unless the onboarding discover is still pending within its deadline: the user’s discover is then superseded and not reported. A pending discover has a deadline of 30 minutes from dispatched_at; past it, it reads as failed with reason timed_out, and the next passing test or a user’s discover may start a new one. After a done discover that found no table, a passing test starts one new discover when the source’s configuration changed since.

Property	Type	Required	Description
`command_id`	string	Yes	Command id of the discover, the id the agent answers on. For a discover a user started, it is the command_id the discover endpoint returned.
Command id of the discover, the id the agent answers on. For a discover a user started, it is the command_id the discover endpoint returned.
`dispatched_at`	string	Yes	When the discover was recorded, before it was sent to the agent or queued for an offline agent.
When the discover was recorded, before it was sent to the agent or queued for an offline agent.
`message`	string	No	For failed, the agent’s message, or the api’s text for agent_not_reachable and timed_out. For done, a note when the discover found no table. Absent otherwise. Diagnostic text, not operator copy. The agent’s text may name the connection’s login, so it is returned only to a caller who may edit sources (sources.write); every other caller receives a generic text derived from reason instead. It never contains a secret.
For failed, the agent’s message, or the api’s text for agent_not_reachable and timed_out. For done, a note when the discover found no table. Absent otherwise. Diagnostic text, not operator copy. The agent’s text may name the connection’s login, so it is returned only to a caller who may edit sources (sources.write); every other caller receives a generic text derived from reason instead. It never contains a secret.
`reason`	string	No	Machine-readable reason of the status. For failed: timed_out (no answer within the deadline), agent_not_reachable (the api could not send or queue the command), or the agent’s own code, such as import_failed or agent_busy, relayed unchanged when it is a code of lowercase letters and underscores of at most 64 characters, and agent_error otherwise. For done: no_tables when the discover found no table. Absent otherwise. Branch on it, not on message. Not an enum: the agent’s codes grow with it.
Machine-readable reason of the status. For failed: timed_out (no answer within the deadline), agent_not_reachable (the api could not send or queue the command), or the agent’s own code, such as import_failed or agent_busy, relayed unchanged when it is a code of lowercase letters and underscores of at most 64 characters, and agent_error otherwise. For done: no_tables when the discover found no table. Absent otherwise. Branch on it, not on message. Not an enum: the agent’s codes grow with it.
`status`	string	Yes	pending: dispatched, or queued while the agent is offline, with no answer yet, within the deadline. done: the agent read the source and the contract is stored. failed: the agent answered with a failure, the api could not send or queue the command, or the deadline passed without an answer; reason says which. The enum is closed: a new value is a contract change. Valid values are: `pending`, `done`, `failed`.
pending: dispatched, or queued while the agent is offline, with no answer yet, within the deadline. done: the agent read the source and the contract is stored. failed: the agent answered with a failure, the api could not send or queue the command, or the deadline passed without an answer; reason says which. The enum is closed: a new value is a contract change. Valid values are: `pending`, `done`, `failed`.

Source First Job

type: SourceFirstJob

What onboarding did about the first job of a data source. When the first discover of a source with no job finishes done and finds at least one table, onboarding creates one job for it in the same environment: the source, the environment’s data platform as target, no objects selected, and one run named once with strategy full and no schedule. No objects selected means every table of the source until the user chooses: the agent reads an empty selection as all tables. Only the source’s first discover creates it, judged by the source’s own history (its first done discover that finds a table), never by catalog contracts; a later discover of a source with no job creates nothing, except to retry a failed or waiting_for_platform first job. The job is a staged change like any other job write: onboarding neither publishes nor runs it. Onboarding creates at most one job per source and environment.

Property	Type	Required	Description
`job_name`	string	No	Name of the created job: the source slug, with a suffix -2, -3 and so on when a job of that name exists in the environment. Present exactly when status is created. The user may rename or delete the job later; onboarding does not create another one.
Name of the created job: the source slug, with a suffix -2, -3 and so on when a job of that name exists in the environment. Present exactly when status is created. The user may rename or delete the job later; onboarding does not create another one.
`message`	string	No	For failed, the validator’s or the database’s reason. Absent otherwise. It never contains a secret.
For failed, the validator’s or the database’s reason. Absent otherwise. It never contains a secret.
`status`	string	Yes	created: the job exists, see job_name. waiting_for_platform: the environment has no data platform whose latest connection test passed; the job is created when a data platform is saved and its connection test passes. failed: the job write was refused and nothing was stored; message says why, and the next discover of the source that finishes done tries again. The enum is closed: a new value is a contract change. Valid values are: `created`, `waiting_for_platform`, `failed`.
created: the job exists, see job_name. waiting_for_platform: the environment has no data platform whose latest connection test passed; the job is created when a data platform is saved and its connection test passes. failed: the job write was refused and nothing was stored; message says why, and the next discover of the source that finishes done tries again. The enum is closed: a new value is a contract change. Valid values are: `created`, `waiting_for_platform`, `failed`.

Last Connection Test

type: LastConnectionTest

The latest connection test of a data platform or data source, failures included: a failing test is kept with its result code and message, so an operator can see why it failed. Only an answer from the project’s pinned agent is recorded.

Present once a test dispatch has been recorded since the connection’s configuration was last saved and since the project’s agent was last re-pinned to a different agent or to none. Either change discards it, a pending test included, so its absence means that no test describes the current configuration.

A test is pending while finished_at is absent, or while the result answers an older command than command_id, because a newer test was dispatched and has not answered yet. The pending field states this, so a client never compares command ids or timestamps itself; dispatched_at can be earlier than the previous answer’s finished_at, so comparing times would read a pending test as answered. While a newer test is pending, finished_at, passed, result and message still describe the previous answered test of the same configuration.

A dispatch is recorded before the test is sent to the agent. When the send then fails, the test endpoint answers 409 and no client receives its command id, yet the recorded test stays pending and never answers. A pending test has no deadline here: it stays pending until the next test, configuration change or re-pin. A client bounds its wait from dispatched_at, and treats a pending test older than its own budget as outcome unknown.

Property	Type	Required	Description
`command_id`	string	Yes	Command id of the latest recorded dispatch. When the test was sent, it is the command_id the test endpoint returned, in the same string form. When the send failed after the dispatch was recorded, no client received it. A newer test replaces it, and the answer to the test it replaced is not recorded.
Command id of the latest recorded dispatch. When the test was sent, it is the command_id the test endpoint returned, in the same string form. When the send failed after the dispatch was recorded, no client received it. A newer test replaces it, and the answer to the test it replaced is not recorded.
`dispatched_at`	string	Yes	When the latest dispatch was recorded.
When the latest dispatch was recorded.
`finished_at`	string	No	When the latest answer was recorded. Absent until a test of the current configuration answers. While pending is true, it belongs to the previous test.
When the latest answer was recorded. Absent until a test of the current configuration answers. While pending is true, it belongs to the previous test.
`message`	string	No	The message as the agent sent it: the note of a success, or the driver’s text and details of a failure. Diagnostic text rather than operator copy. Absent when the agent sent none, as on a data-source success from agents through v4.11.1.
The message as the agent sent it: the note of a success, or the driver’s text and details of a failure. Diagnostic text rather than operator copy. Absent when the agent sent none, as on a data-source success from agents through v4.11.1.
`passed`	boolean	No	Whether the answered test passed. A pass is what earns the verified status; false means a failing result. Present exactly when finished_at is.
Whether the answered test passed. A pass is what earns the verified status; false means a failing result. Present exactly when finished_at is.
`pending`	boolean	Yes	True while the latest test, command_id, has no recorded answer: finished_at is absent, or the result answers an older test. False once its answer is recorded.
True while the latest test, command_id, has no recorded answer: finished_at is absent, or the result answers an older test. False once its answer is recorded.
`result`	string	No	The result code as the agent sent it, relayed unchanged. Branch on it, not on message. For a data platform, every answer carries one of the codes the data-platform connection test lists. For a data source, agents through v4.11.1 send no code on a success, so the field is absent, and `connection_failed` on every failure, with the driver’s text in message. Later agents may send further source codes, such as `no_tables_yet` and `read_access_not_checked`. Any other reason, such as `invalid_request` or `handler_not_configured`, means the agent refused the command, and `handler_incomplete` that the command was lost.
The result code as the agent sent it, relayed unchanged. Branch on it, not on message. For a data platform, every answer carries one of the codes the data-platform connection test lists. For a data source, agents through v4.11.1 send no code on a success, so the field is absent, and `connection_failed` on every failure, with the driver’s text in message. Later agents may send further source codes, such as `no_tables_yet` and `read_access_not_checked`. Any other reason, such as `invalid_request` or `handler_not_configured`, means the agent refused the command, and `handler_incomplete` that the command was lost.

Configure Project Source Request

type: ConfigureProjectSourceRequest

Create or update a project’s data-source connection. Secret fields are write-only.

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the source.
Agent type connecting to the source.
`config`	object	No	Non-secret connection fields (host, port, database, schema).
Non-secret connection fields (host, port, database, schema).
`secret`	object	No	Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
`source_slug`	string	Yes	URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
URL-safe source slug — the ADR-067 cross-plane key; equals the PCF sources[].name.
`type`	string	Yes	Connector type slug, e.g. ‘postgres’.
Connector type slug, e.g. ‘postgres’.

Schedule State List

type: ScheduleStateList

The scheduling state of a project’s jobs in one environment.

Property	Type	Required	Description
`data`	ScheduleState []	Yes	One entry per scheduled entry across the project’s jobs. A job with no scheduled entries contributes nothing.
One entry per scheduled entry across the project’s jobs. A job with no scheduled entries contributes nothing.

Schedule State

type: ScheduleState

The control plane’s scheduling state for one scheduled entry of a job. Present only while that entry carries a cron expression; an entry that runs on demand has no ScheduleState at all.

Property	Type	Required	Description
`job_name`	string	Yes	Name of the job the schedule belongs to. Examples: `orders_nightly`.
Name of the job the schedule belongs to. Examples: `orders_nightly`.
`last_fired_at`	[string null]	No	When the control plane last dispatched this entry. Always present on the wire; null means no dispatch is currently recorded for it. Examples: `2026-09-16T03:00:00Z`.
When the control plane last dispatched this entry. Always present on the wire; null means no dispatch is currently recorded for it. Examples: `2026-09-16T03:00:00Z`.
`next_run_at`	[string null]	No	The control plane’s computed next fire for this entry. Always present on the wire; null means no next fire is currently known, which is not the same as the entry having no schedule at all — an entry with no schedule is absent from this list rather than present with a null timestamp. It is null while the entry is paused; on resume it is computed from the time of the resume. It is an instant; a client shows it in the project’s time_zone, which the project read carries. Examples: `2026-09-17T03:00:00Z`.
The control plane’s computed next fire for this entry. Always present on the wire; null means no next fire is currently known, which is not the same as the entry having no schedule at all — an entry with no schedule is absent from this list rather than present with a null timestamp. It is null while the entry is paused; on resume it is computed from the time of the resume. It is an instant; a client shows it in the project’s time_zone, which the project read carries. Examples: `2026-09-17T03:00:00Z`.
`pause_reason`	[string null]	No	The reason the operator gave when pausing the entry. Always present on the wire; null while the entry is not paused. Examples: `source maintenance`.
The reason the operator gave when pausing the entry. Always present on the wire; null while the entry is not paused. Examples: `source maintenance`.
`paused`	boolean	Yes	Whether an operator paused this entry (pauseJobSchedule). A paused entry starts no new run until it is resumed. Pause is operational state set by an operator, not part of the job document. Examples: `false`.
Whether an operator paused this entry (pauseJobSchedule). A paused entry starts no new run until it is resumed. Pause is operational state set by an operator, not part of the job document. Examples: `false`.
`paused_at`	[string null]	No	When the entry was paused. Always present on the wire; null while the entry is not paused. Examples: `2026-10-09T08:00:00Z`.
When the entry was paused. Always present on the wire; null while the entry is not paused. Examples: `2026-10-09T08:00:00Z`.
`paused_by`		No	The account that paused the entry. Always present on the wire; null while the entry is not paused.
The account that paused the entry. Always present on the wire; null while the entry is not paused.
`run_name`	string	Yes	Name of the scheduled entry within the job. Matches the name of the corresponding entry in the job document’s runs list, which is the join key between the two payloads. Examples: `nightly`.
Name of the scheduled entry within the job. Matches the name of the corresponding entry in the job document’s runs list, which is the join key between the two payloads. Examples: `nightly`.
`schedule`	string	Yes	The cron expression as authored on the job, evaluated in the project’s time_zone. The control plane maintains its own scheduling state from this value, so next_run_at and last_fired_at may trail an edit to it. Examples: `0 3 * * *`.
The cron expression as authored on the job, evaluated in the project’s time_zone. The control plane maintains its own scheduling state from this value, so next_run_at and last_fired_at may trail an edit to it. Examples: `0 3 * * *`.

Schedule Actor

type: ScheduleActor

The account that performed an operator action on a schedule.

Property	Type	Required	Description
`display_name`	string	Yes	The account’s display name, resolved when the state is read. Examples: `Anna`.
The account’s display name, resolved when the state is read. Examples: `Anna`.
`id`	string	Yes	Account identifier.
Account identifier.

Trigger Run Request

type: TriggerRunRequest

Request body for triggering a run of one named job from the control plane. A body names the job with job_name; a body from an older client may name the source with the deprecated source_slug instead. Both are optional in the schema so older clients stay valid; the api rejects a body that names neither with HTTP 400.

Property	Type	Required	Description
`dry_run`	boolean	No	When true the run executes in dry-run mode (no data written).
When true the run executes in dry-run mode (no data written).
`environment_id`	string	Yes	DTAP environment slug (e.g. production). Examples: `production`.
DTAP environment slug (e.g. production). Examples: `production`.
`job_name`	string	No	Name of the job to run, unique within the environment. Send it on every new request. The api rejects a body with neither job_name nor source_slug with HTTP 400. Examples: `sales_daily`.
Name of the job to run, unique within the environment. Send it on every new request. The api rejects a body with neither job_name nor source_slug with HTTP 400. Examples: `sales_daily`.
`source_slug`	string	No	Deprecated: send job_name. Catalog source slug, accepted only as a fallback for older clients: when the source has exactly one job, that job runs; when it has more than one, the request fails with HTTP 409. When sent with job_name, it must name the job’s source, or the request fails with HTTP 400. A body with neither job_name nor source_slug fails with HTTP 400.
Deprecated: send job_name. Catalog source slug, accepted only as a fallback for older clients: when the source has exactly one job, that job runs; when it has more than one, the request fails with HTTP 409. When sent with job_name, it must name the job’s source, or the request fails with HTTP 400. A body with neither job_name nor source_slug fails with HTTP 400.
`strategy`	string	No	Load strategy for this run only; the job does not change. absent = the strategy of the job’s first run entry (full when the job has no run entry); `cdc` is not accepted. Valid values are: `full`, `incremental`. Examples: `full`.
Load strategy for this run only; the job does not change. absent = the strategy of the job’s first run entry (full when the job has no run entry); `cdc` is not accepted. Valid values are: `full`, `incremental`. Examples: `full`.

Run Trigger Ref

type: RunTriggerRef

Reference returned when a run is dispatched from the control plane.

Property	Type	Required	Description
`cmd_id`	string	Yes	Correlation key linking this dispatch to the agent’s run_started telemetry.
Correlation key linking this dispatch to the agent’s run_started telemetry.
`status`	string	Yes	queued \| queued_offline
queued \| queued_offline

Repository Move

type: RepositoryMove

A project’s latest repository check or move (api#1090). Never carries a credential.

Property	Type	Required	Description
`branches`	RepositoryMoveBranch []	Yes	Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
Every branch the move writes in the target, with what happens to it and, once a move started, its progress.
`configuration`	RepositoryMoveConfiguration	No

`differences`	RepositoryMoveDifference []	No	Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
Connections the adopted branches set differently from the project’s environments. They are reported, never applied.
`display_name`	string	Yes	The target repository’s display name.
The target repository’s display name.
`earlier_partial_move`	string[]	No	Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
Target branches that already hold this project’s commits from an earlier move that did not finish; a move completes them.
`error`	Error	No

`finished_at`	string	No	When the check or move ended. Absent while it runs.
When the check or move ended. Absent while it runs.
`git_repo_url`	string	Yes	The target repository’s address.
The target repository’s address.
`kind`	string	No	move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
move: the target holds no configuration, so the project’s history and every environment branch move there. adopt: the target holds a readable configuration that main and Development take (S16, S16a). Absent until a check decided it. Valid values are: `move`, `adopt`.
`missing_connections`	RepositoryMoveConnection []	No	Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
Sources and data platforms the adopted configuration names that the project does not have (state refused, code connections_missing, S4).
`paused_until`	string	No	Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
Until when the automatic retry of a failed managed repository pauses for this check or move (S18). Absent when nothing pauses it.
`proposals`	string	No	For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
For an adoption: created when the customer’s branches for pinned environments wait in `proposal/<environment>`; deferred_until_split while each environment branch still carries its full configuration (before core#336), when adoption replaces Development’s configuration only and the other environments wait for the split. Valid values are: `created`, `deferred_until_split`.
`running`	boolean	No	True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
True while a move runs (state moving or adopting under a live lease). A move whose run was interrupted reads as state failed, error move_failed, running false.
`started_at`	string	Yes	When the check or move began.
When the check or move began.
`starting_point`	string	Yes	The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
The project’s repository when the check or move began: managed (the platform’s), own (a customer repository), failed (the managed repository could not be created) or none (no git host is configured, S19). Valid values are: `managed`, `own`, `failed`, `none`.
`state`	RepositoryMoveState	Yes

`target`	string	No	What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
What the check found on the configuration paths (S11): empty (no commits), other_files (commits, no configuration file), configuration (a configuration file on a branch the project would use). Absent before the target was read. Valid values are: `empty`, `other_files`, `configuration`.
`unmapped_branches`	string[]	No	Target branches that map to no bound environment; they are ignored and left as they are.
Target branches that map to no bound environment; they are ignored and left as they are.
`unreadable_files`	string[]	No	Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).
Configuration files the check could not read, as `<branch>:<path>` (state refused, code configuration_unreadable).

Repository Move Branch

type: RepositoryMoveBranch

One branch a move writes in the target.

Property	Type	Required	Description
`action`	string	Yes	move: pushed with its full history. join: the target had the branch, so a commit with both tips as parents joins them. create: the environment had no branch; it is created with the environment’s configuration as its first commit. replace: main or Development takes the adopted configuration through a joining commit. created_from_main: Development had no branch in the target and is created from the adopted main (S5). keep_version: the environment keeps its pinned version; the target has no branch for it. proposal: the environment keeps its pinned version and the target’s branch for it waits in `proposal/<environment>`. Valid values are: `move`, `join`, `create`, `replace`, `created_from_main`, `keep_version`, `proposal`.
move: pushed with its full history. join: the target had the branch, so a commit with both tips as parents joins them. create: the environment had no branch; it is created with the environment’s configuration as its first commit. replace: main or Development takes the adopted configuration through a joining commit. created_from_main: Development had no branch in the target and is created from the adopted main (S5). keep_version: the environment keeps its pinned version; the target has no branch for it. proposal: the environment keeps its pinned version and the target’s branch for it waits in `proposal/<environment>`. Valid values are: `move`, `join`, `create`, `replace`, `created_from_main`, `keep_version`, `proposal`.
`environment_id`	string	No	The bound environment the branch belongs to; absent for main and proposal branches.
The bound environment the branch belongs to; absent for main and proposal branches.
`name`	string	Yes	The branch’s name in the target.
The branch’s name in the target.
`proposal`	string	No	The proposal branch, `proposal/<environment>`, for action proposal.
The proposal branch, `proposal/<environment>`, for action proposal.
`state`	string	No	The branch’s progress once a move started. Valid values are: `waiting`, `moving`, `moved`, `failed`.
The branch’s progress once a move started. Valid values are: `waiting`, `moving`, `moved`, `failed`.
`updated_at`	string	No	When the branch reached its state.
When the branch reached its state.

Repository Move Configuration

type: RepositoryMoveConfiguration

The configuration the check found in the target, for an adoption.

Property	Type	Required	Description
`contracts`	string[]	Yes	The data contract files the adopted configuration carries.
The data contract files the adopted configuration carries.
`project_name`	string	Yes	The project name in the target’s amfelt.yaml.
The project name in the target’s amfelt.yaml.
`project_name_differs`	boolean	Yes	True when it is not this project’s name. The project keeps its own name (S14).
True when it is not this project’s name. The project keeps its own name (S14).

Repository Move Difference

type: RepositoryMoveDifference

A connection an adopted branch sets differently from the project’s environment.

Property	Type	Required	Description
`branch`	string	Yes	The target branch the difference was found on.
The target branch the difference was found on.
`environment_id`	string	No	The environment the branch maps to.
The environment the branch maps to.
`field`	string	Yes	What differs: plugin, secret_ref, or presence (named on one side only).
What differs: plugin, secret_ref, or presence (named on one side only).
`kind`	string	Yes	Whether it is a source or a data platform. Valid values are: `source`, `platform`.
Whether it is a source or a data platform. Valid values are: `source`, `platform`.
`name`	string	Yes	The connection’s name.
The connection’s name.

Repository Move Connection

type: RepositoryMoveConnection

A source or data platform the adopted configuration names.

Property	Type	Required	Description
`kind`	string	Yes	Whether it is a source or a data platform. Valid values are: `source`, `platform`.
Whether it is a source or a data platform. Valid values are: `source`, `platform`.
`name`	string	Yes	Its name in the configuration.
Its name in the configuration.

Repository Move State

type: RepositoryMoveState

checking: a check runs. checked: the check found the target usable. refused: the check refused it (error names the code). moving or adopting: a move runs; publishing waits. moved or adopted: every environment uses the new repository. failed: the move did not finish and the project stays on its repository. cancelled: an owner or admin ended the flow.

Repository Move Request

type: RepositoryMoveRequest

The customer’s repository to move the project to (api#1090). The token is write-only: it is stored in the project’s vault entry when the move succeeds, and never returned or logged.

Property	Type	Required	Description
`display_name`	string	No	The repository’s display name; the last part of the URL when absent.
The repository’s display name; the last part of the URL when absent.
`dry_run`	boolean	No	true runs the check only (D3): nothing changes, and the answer is 200 with the verdict.
true runs the check only (D3): nothing changes, and the answer is 200 with the verdict.
`git_repo_url`	string	Yes	The HTTPS address of one git repository on a host that supports git-https/v1, for example https://git.example.com/acme/config . It carries no credential.
The HTTPS address of one git repository on a host that supports git-https/v1, for example https://git.example.com/acme/config . It carries no credential.
`token`	string	Yes	An access token with read and write access to the repository contents.
An access token with read and write access to the repository contents.

Discover Response

type: DiscoverResponse

Property	Type	Required	Description
`command_id`	string	Yes	The dispatched command id, for correlating run events.
The dispatched command id, for correlating run events.

Project Platform

type: ProjectPlatform

A project’s target data-platform connection (non-secret view). The stored secret is never returned. The latest connection test, failures included, is in last_test.

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the platform.
Agent type connecting to the platform.
`config`	object	No	Non-secret connection fields resolved from the vault (host, port, account, database, schema, warehouse). Never contains secret values.
Non-secret connection fields resolved from the vault (host, port, account, database, schema, warehouse). Never contains secret values.
`configured`	boolean	Yes	True once a connection has been registered in the vault.
True once a connection has been registered in the vault.
`last_test`	LastConnectionTest	No

`name`	string	Yes	Human-readable platform name.
Human-readable platform name.
`status`	string	Yes	Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, error. Never ‘failing’: a run failure may have failed source-side and is not evidence the target platform is unhealthy. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest successful run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active. A passing test that is newer makes it verified. A failing test that is newer makes it configured, with the failure’s result code and message in last_test; a later successful run takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the connection’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active when a successful run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
Evidence-backed status (ADR-098). One of unconfigured, configured, verified, active, error. Never ‘failing’: a run failure may have failed source-side and is not evidence the target platform is unhealthy. Derived per request; never stored. The stored state is one of unconfigured, configured, verified and error, and unconfigured and error are returned as stored. For a stored configured or verified, newest evidence wins between the latest successful run and the latest answered connection test (last_test.finished_at), and status_evidence_at cites the winner. A run that is newer makes the status active. A passing test that is newer makes it verified. A failing test that is newer makes it configured, with the failure’s result code and message in last_test; a later successful run takes over again. On equal times, a passing test wins and the run wins over a failing test, so a failing test must be strictly newer than the run to decide the status. With neither a run nor an answered test, the status is configured. verified means the latest answered connection test of the current configuration passed, run by the project’s pinned agent. Saving the connection’s configuration through this API, or re-pinning the project’s agent to a different agent or to none, discards the test evidence, a pending test included. The status is then derived from runs as before: active when a successful run stands as evidence, configured otherwise. A change to the secret made outside this API’s configuration save, such as a secret rotated externally or updated without a configuration write, does not discard it: verified describes the secret as it resolved when the test ran.
`status_evidence_at`	string	Yes	Timestamp of the evidence behind status — the run’s finished_at for active; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
Timestamp of the evidence behind status — the run’s finished_at for active; last_test.finished_at, when the answer was recorded, for verified and for a configured whose newest evidence is a failing test; the configuration row’s updated_at otherwise. A status is not renderable without it.
`status_evidence_run_id`	integer	No	The run that is the evidence, when a run is the evidence. Absent otherwise.
The run that is the evidence, when a run is the evidence. Absent otherwise.
`type`	string	Yes	Connector type slug, e.g. ‘snowflake’.
Connector type slug, e.g. ‘snowflake’.

Configure Project Platform Request

type: ConfigureProjectPlatformRequest

Upsert the project’s target data-platform connection. Secret fields are write-only.

Property	Type	Required	Description
`agent`	string	Yes	Agent type connecting to the platform.
Agent type connecting to the platform.
`config`	object	No	Non-secret connection fields (host, port, account, database, schema, warehouse).
Non-secret connection fields (host, port, account, database, schema, warehouse).
`name`	string	Yes	Human-readable platform name.
Human-readable platform name.
`secret`	object	No	Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
Write-only secret connection fields (e.g. password, key). Omit or send blank values to keep the current secret. Never returned on read.
`type`	string	Yes	Connector type slug, e.g. ‘snowflake’.
Connector type slug, e.g. ‘snowflake’.

Project Member List

type: ProjectMemberList

A page of project members.

Property	Type	Required	Description
`data`	ProjectMember []	Yes	The page of members.
The page of members.
`next_cursor`	[string null]	No	Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.
Opaque cursor for the next page, or null when this is the final page. Examples: `eyJpZCI6OTk5fQ`.

Project Member

type: ProjectMember

A member of a project.

Property	Type	Required	Description
`account_id`	string	Yes	Identifier of the member’s account.
Identifier of the member’s account.
`email`	string	Yes	Email address of the member.
Email address of the member.
`first_name`	string	No	Given name of the member.
Given name of the member.
`id`	string	Yes	Identifier of the project membership.
Identifier of the project membership.
`joined_at`	string	Yes	Timestamp the member joined the project.
Timestamp the member joined the project.
`last_name`	string	No	Family name of the member.
Family name of the member.
`role`	ProjectRole	Yes

`status`	string	Yes	Status of the membership. Examples: `active`.
Status of the membership. Examples: `active`.

Project Role

type: ProjectRole

Role of an account within a project. The org owns projects, so there is no project owner.

Project Member Create

type: ProjectMemberCreate

The payload for adding an organization member to a project.

Property	Type	Required	Description
`account_id`	string	Yes	Identifier of the account to add. Must be an active member of the organization that owns the project.
Identifier of the account to add. Must be an active member of the organization that owns the project.
`role`	ProjectRole	Yes

Job List

type: JobList

A project’s jobs.

Property	Type	Required	Description
`data`	Job []	Yes	The jobs.
The jobs.

Job

type: Job

A configured job — the whole-document surface for ADR-074 (source, selection, runs).

Property	Type	Required	Description
`name`	string	Yes	Job name.
Job name.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	ADR-067 cross-plane key; equals the PCF sources[].name.
ADR-067 cross-plane key; equals the PCF sources[].name.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.
`updated_at`	string	No	When the job was last updated.
When the job was last updated.
`warnings`	JobWarning []	No	Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.
Set on the responses of createProjectJob and putProjectJob only, for a job that was saved: conditions that do not refuse the write. Absent or empty on reads and when there is nothing to report.

Job Run

type: JobRun

A scheduled or on-demand execution definition within a job (ADR-074).

Property	Type	Required	Description
`name`	string	Yes	Run name, unique within the job.
Run name, unique within the job.
`schedule`	string	No	Cron expression; omitted means on-demand only.
Cron expression; omitted means on-demand only.
`strategy`	string	Yes	Load strategy. Valid values are: `full`, `incremental`, `cdc`.
Load strategy. Valid values are: `full`, `incremental`, `cdc`.

Job Select

type: JobSelect

The job’s object-selection rules and per-object overrides.

Property	Type	Required	Description
`defaults`	object	No	select.defaults (historyMode/writeMode); validated server-side.
select.defaults (historyMode/writeMode); validated server-side.
`exclude`	string[]	No	Glob patterns selecting objects to exclude.
Glob patterns selecting objects to exclude.
`include`	string[]	No	Glob patterns selecting objects to include.
Glob patterns selecting objects to include.
`objects`	object	No	Per-object overrides, keyed by object glob.
Per-object overrides, keyed by object glob.

Job Object Override

type: JobObjectOverride

Per-object override payload (ADR-068 surface — tableType, historyMode, cursor, column axes). Validated server-side against the PCF ObjectOverride schema (ADR-069); a failing object answers 400 job_validation_failed (JobValidationError).

The incremental fields. cursor names the column; cursorType is timestamp or sequence and is required when cursor is set and a run loads incrementally, with no default guess. lookback re-reads a trailing slice on every run: a duration text for a timestamp cursor (default 5m) or a non-negative integer for a sequence cursor (default 0). deleteDetection is none, fullRun (the default), keyScan or softDelete; softDelete needs softDeleteColumn and softDeleteValue. window reloads a trailing slice by column: its size is a Go duration such as 168h (day units such as 7d are rejected) and defaults to lateArrivalThreshold; with neither set the window is invalid. keyScan is accepted but runs only once amfeltlabs/plugin-sdk#371 ships; the agent reports a warning until then. The business key is not an override field: it lives in the ODCS contract (ADR-058), and a businessKey field is rejected as unknown.

Job Warning

type: JobWarning

A condition the api saved a job despite, one per affected environment.

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token. agent_upgrade_required: a run of the job loads incrementally and the environment’s agent is below the incremental floor; the run is refused until the agent is upgraded (ErrorCode). Examples: `agent_upgrade_required`.
Stable, snake_case token. agent_upgrade_required: a run of the job loads incrementally and the environment’s agent is below the incremental floor; the run is refused until the agent is upgraded (ErrorCode). Examples: `agent_upgrade_required`.
`environment`	string	Yes	DTAP environment slug the warning applies to. Examples: `production`.
DTAP environment slug the warning applies to. Examples: `production`.
`message`	string	Yes	Human-readable description naming the agent version and the floor.
Human-readable description naming the agent version and the floor.

Create Job Request

type: CreateJobRequest

A complete job to create. The name must be unused within the project and environment; creation never replaces an existing job.

Property	Type	Required	Description
`name`	string	Yes	Job name.
Job name.
`rebuild_history`	boolean	No	Confirms that the new job may change the history mode of objects whose history already exists on its target, dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a job is not created: the request answers 409 history_rebuild_required. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
Confirms that the new job may change the history mode of objects whose history already exists on its target, dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a job is not created: the request answers 409 history_rebuild_required. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	Name of the project source this job reads from.
Name of the project source this job reads from.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.

Job Validation Error

type: JobValidationError

The 400 body of createProjectJob and putProjectJob when select.objects fails validation. It is the standard Error envelope’s fields, plus objects. With code job_validation_failed, objects lists every failing object, not only the first, so a client can show all of them at once; nothing is saved. Any other code is an Error as the operation describes it, without objects.

Property	Type	Required	Description
`code`	string	Yes	As Error.code; job_validation_failed when objects fail validation. Examples: `job_validation_failed`.
As Error.code; job_validation_failed when objects fail validation. Examples: `job_validation_failed`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	JobObjectValidationError []	No	Set with code job_validation_failed; one entry per failing object.
Set with code job_validation_failed; one entry per failing object.

Job Object Validation Error

type: JobObjectValidationError

One object of select.objects that failed validation.

Property	Type	Required	Description
`cause`	string	Yes	Why the field was refused, naming the allowed values where there are any. Examples: `must be one of timestamp, sequence`.
Why the field was refused, naming the allowed values where there are any. Examples: `must be one of timestamp, sequence`.
`field`	string	Yes	The override field at fault, as written in the request. Examples: `cursorType`.
The override field at fault, as written in the request. Examples: `cursorType`.
`object`	string	Yes	The select.objects key, an object glob. Examples: `sales.orders`.
The select.objects key, an object glob. Examples: `sales.orders`.

History Rebuild Conflict

type: HistoryRebuildConflict

The 409 body of the four writes the api’s history-mode guard applies to: createProjectJob, putProjectJob, approveProjectCatalogObjectClassification and changeProjectCatalogObjectClassification. It is the standard Error envelope’s fields, plus objects. With code history_rebuild_required, objects lists each object and target whose existing history the change would drop, so a client can ask for confirmation and send the same write again with rebuild_history true. Any other code is a conflict as the operation describes it, without objects.

The guarantee is the run-time refusal, not this 409. An agent built on this contract refuses to load an object’s existing history table on a target in a history mode other than the one that history was built in, unless listPendingHistoryRebuilds names a pending rebuild of that object on that target to that mode, which the run then carries out (HistoryRebuild). The built mode the refusal compares against is the one the api records (listHistoryStates). When the api records none for that object on that target, the agent adopts the history mode its run resolves and loads the history in that mode, and that run is not refused; the api records the mode that run’s finished, non-skipped history task reports with TaskUpdate.history_mode and target (HistoryState). History loaded before the api recorded built modes cannot be verified. A refused object stops after staging and waits, with awaiting_rebuild_confirmation (ObjectWaitReason), and the refused task reports the built mode (TaskUpdate.history_mode), which the api does not record (HistoryState). The refusal is agent work tracked on amfeltlabs/agent#831; the api does not enforce it. For an object whose built mode is recorded, it covers every change of the object’s history mode that the guard does not: the writes that never answer history_rebuild_required (postProjectEnvironmentRepoPush, postProjectEnvironmentRepoImport, postProjectEnvironmentRepoRestore, putProjectCatalogContract, putProjectEnvironmentRepo, moveProjectRepository and configureProjectPlatform among them), and configuration that reaches an agent without an API write, such as a commit made directly in the customer’s repository; one with no record adopts the mode its run resolves.

The api’s guard is a usability step on the customer screens’ writes, so a person confirms a rebuild before a run refuses. The api learns the mode an object’s history on a target was built in from the history_mode and target an agent reports with a finished, non-skipped history task (TaskUpdate), and from a completed rebuild, never from a failed or skipped task (HistoryState). On each of the four writes, the guard checks each object the write configures, on each target where the api knows that object’s built mode, against that built mode, never against the configuration before the write. Let new be the object’s effective history mode after the write. When new is the built mode, nothing needs confirming, and a pending rebuild of the object on that target is canceled. When a pending rebuild of the object on that target to new already exists, nothing needs confirming and it stays pending. Otherwise the write answers 409 history_rebuild_required, naming the object and target in objects, and changes nothing, unless it sets rebuild_history true; confirmed, it cancels any pending rebuild of the object on that target and records a new pending one from the built mode to new (HistoryRebuild). This is what “a write that changes the history mode of an object whose history already exists” means wherever a guarded write says it. Where the api knows no built mode for an object on a target, the guard does not answer 409 for it and records no rebuild there: the next run adopts the history mode it resolves and reports it, and that run is not refused. Once that run’s finished, non-skipped history task has reported the mode it ran in, the api records it (HistoryState) and the guard knows it.

Property	Type	Required	Description
`code`	string	Yes	As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
As Error.code; history_rebuild_required when the write needs a rebuild confirmation. Examples: `history_rebuild_required`.
`field`	string	No	As Error.field.
As Error.field.
`message`	string	Yes	As Error.message.
As Error.message.
`objects`	HistoryModeChange []	No	Set with code history_rebuild_required; the objects the change would rebuild.
Set with code history_rebuild_required; the objects the change would rebuild.

History Mode Change

type: HistoryModeChange

One object whose history mode a write would change while its history exists on a target. An object whose history exists on two targets is named once per target.

Property	Type	Required	Description
`history_mode`	string	Yes	The history mode the existing history was built in. Examples: `scd1`.
The history mode the existing history was built in. Examples: `scd1`.
`new_history_mode`	string	Yes	The history mode the write asks for. Examples: `scd2`.
The history mode the write asks for. Examples: `scd2`.
`object_name`	string	Yes	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).
`source_slug`	string	Yes

`target`	string	Yes	The target platform slug the existing history is on.
The target platform slug the existing history is on.

Project Environment List

type: ProjectEnvironmentList

A project’s bound environments.

Property	Type	Required	Description
`data`	ProjectEnvironment []	Yes

Project Environment

type: ProjectEnvironment

A project’s binding to a DTAP environment.

Property	Type	Required	Description
`agent_commit_reported_at`	[string null]	No	When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
When the agent last reported agent_commit_sha. Absent or null when agent_commit_sha is unknown.
`agent_commit_sha`	[string null]	No	Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit the environment’s agent last reported it holds: the actual commit (ADR-129 decision 5). It differs from deployed_commit_sha while the agent has not yet picked up the deployment. Absent or null means unknown: the agent has not reported, or is an older agent that does not report its commit. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`agent_id`	[string null]	No	The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
The agent that executes this environment (exec.project_environment.agent_id). Absent or null when no agent is bound to it.
`deployed_commit_sha`	[string null]	No	Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
Full SHA of the configuration commit this environment is declared to be deployed at: the declared commit (ADR-129 decision 5). Absent or null means no deployment is recorded yet. Examples: `8f14e45fceea167a5a36dedd4bea2543c3a6f7b2`.
`environment_id`	string	Yes	The DTAP environment slug.
The DTAP environment slug.
`id`	string	Yes	Binding identifier.
Binding identifier.
`name`	string	Yes	Environment display name.
Environment display name.
`project_id`	string	Yes	The project.
The project.
`sort_order`	integer	Yes	DTAP promotion order (ascending).
DTAP promotion order (ascending).

Project Environment Create

type: ProjectEnvironmentCreate

The payload for binding a project to an environment.

Property	Type	Required	Description
`environment_id`	string	Yes	The DTAP environment slug to bind.
The DTAP environment slug to bind.

Assign Project Agent Request

type: AssignProjectAgentRequest

The payload for pinning an executing agent on a project, or on one of its environments.

Property	Type	Required	Description
`agent_id`	string	Yes	The agent to pin as the executing agent — must be an active agent in the same tenant.
The agent to pin as the executing agent — must be an active agent in the same tenant.

Project Update

type: ProjectUpdate

The mutable fields of a project.

Property	Type	Required	Description
`display_name`	string	Yes	New human-readable name for the project.
New human-readable name for the project.
`time_zone`	string	No	New IANA time zone name for the project. Omitted, the project keeps its time zone. Examples: `Europe/Amsterdam`.
New IANA time zone name for the project. Omitted, the project keeps its time zone. Examples: `Europe/Amsterdam`.

Project Member Update

type: ProjectMemberUpdate

The mutable fields of a project member.

Property	Type	Required	Description
`role`	ProjectRole	Yes

Put Job Request

type: PutJobRequest

Create or replace a job (full replace of select, runs, and object overrides).

Property	Type	Required	Description
`rebuild_history`	boolean	No	Confirms that the replacement may change the history mode of objects whose history already exists on a target (through select.objects or select.defaults), dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a replacement answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
Confirms that the replacement may change the history mode of objects whose history already exists on a target (through select.objects or select.defaults), dropping that history; the next run rebuilds it from current staging in the new mode. Without it, such a replacement answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when no such object is affected. Not stored.
`runs`	JobRun []	Yes	The job’s run definitions.
The job’s run definitions.
`select`	JobSelect	Yes

`source_slug`	string	Yes	ADR-067 cross-plane key; equals the PCF sources[].name.
ADR-067 cross-plane key; equals the PCF sources[].name.
`target`	[string null]	No	Target platform slug; omitted or null means the environment’s platform.
Target platform slug; omitted or null means the environment’s platform.

Server Status List

type: ServerStatusList

The configured servers’ status for a project + environment.

Property	Type	Required	Description
`data`	ServerStatus []	Yes	The status rows.
The status rows.

Server Status

type: ServerStatus

One configured server’s status row for a project + environment.

Property	Type	Required	Description
`name`	string	Yes	Server (data platform / source) name.
Server (data platform / source) name.
`status`	string	Yes	Stored configuration lifecycle — one of unconfigured, configured, verified, error. verified means the latest answered connection test of the current configuration passed, and verified_at cites it. Not derived from runs, so never active or failing.
Stored configuration lifecycle — one of unconfigured, configured, verified, error. verified means the latest answered connection test of the current configuration passed, and verified_at cites it. Not derived from runs, so never active or failing.
`type`	string	Yes	Connector type slug, e.g. ‘snowflake’.
Connector type slug, e.g. ‘snowflake’.
`updated_at`	string	Yes	When the server’s configuration last changed. Recording a connection test does not move it.
When the server’s configuration last changed. Recording a connection test does not move it.
`verified_at`	string	No	When the passing connection test’s answer was recorded: the evidence a verified status cites. Present only when status is verified.
When the passing connection test’s answer was recorded: the evidence a verified status cites. Present only when status is verified.

Repo Tree Entries

type: RepoTreeEntries

The committed config tree at one commit: every path, its artifact class, and its size — never content. Distinct from RepoTree (the agent’s git-lite pull response), which carries full file content for a different consumer.

Property	Type	Required	Description
`entries`	RepoTreeEntry []	Yes	One entry per file. Empty when the branch has no commits yet.
One entry per file. Empty when the branch has no commits yet.
`head_sha`	string	Yes	The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
`modified_at_truncated`	boolean	No	Present only when include=modified_at was requested. True means the history walk exhausted its budget while paths were still undated, so a null modified_at means “we stopped looking” rather than “no commit touched this path”. False means the walk reached the end of history, and any remaining null is a genuine absence. Without this flag the two cases are indistinguishable, and a client cannot tell a user which one it is looking at.
Present only when include=modified_at was requested. True means the history walk exhausted its budget while paths were still undated, so a null modified_at means “we stopped looking” rather than “no commit touched this path”. False means the walk reached the end of history, and any remaining null is a genuine absence. Without this flag the two cases are indistinguishable, and a client cannot tell a user which one it is looking at.
`ref`	string	Yes	The commit the entries were read at. Echoed back so a client can pin follow-up file reads to the same commit — a (ref, path) pair is immutable and therefore safe to cache.
The commit the entries were read at. Echoed back so a client can pin follow-up file reads to the same commit — a (ref, path) pair is immutable and therefore safe to cache.

Repo Tree Entry

type: RepoTreeEntry

Property	Type	Required	Description
`class`	string	Yes	The artifact class this path belongs to. “docs” is generated source documentation, which the platform writes and a customer reads rather than edits. “other” means the path matched no registered class and is shown as a plain file rather than hidden — an unrecognized file is still the customer’s, and stays last in this list because it is the fallback rather than a peer of the named classes. Valid values are: `config`, `contract`, `template`, `docs`, `other`.
The artifact class this path belongs to. “docs” is generated source documentation, which the platform writes and a customer reads rather than edits. “other” means the path matched no registered class and is shown as a plain file rather than hidden — an unrecognized file is still the customer’s, and stays last in this list because it is the fallback rather than a peer of the named classes. Valid values are: `config`, `contract`, `template`, `docs`, `other`.
`modified_at`	[string null]	No	The authored time of the most recent commit that touched this path. Authored rather than committed time, so this agrees with the commit list’s own timestamps for the same commit. Absent unless include=modified_at was requested. Null when it WAS requested and this path was not reached — see modified_at_truncated on the enclosing response for whether that means “no commit in this history touched it” or “we stopped looking”.
The authored time of the most recent commit that touched this path. Authored rather than committed time, so this agrees with the commit list’s own timestamps for the same commit. Absent unless include=modified_at was requested. Null when it WAS requested and this path was not reached — see modified_at_truncated on the enclosing response for whether that means “no commit in this history touched it” or “we stopped looking”.
`path`	string	Yes	Repo-relative path (e.g. “amfelt.yaml”, “contracts/sales.odcs.yaml”).
Repo-relative path (e.g. “amfelt.yaml”, “contracts/sales.odcs.yaml”).
`size`	integer	Yes	Size in bytes of the file’s committed content.
Size in bytes of the file’s committed content.

Repo Tree

type: RepoTree

The committed config tree and branch HEAD SHA.

Property	Type	Required	Description
`base_sha`	string	Yes	DEPRECATED — use head_sha, which holds the same value under the name the rest of this schema family uses. This field is the branch tip. It does NOT mean what RepoStatus.base_sha means: there, base_sha is the last SHA the control plane pushed, deliberately not the tip, and external_change is defined as the two differing. Removal waits for a major version.
DEPRECATED — use head_sha, which holds the same value under the name the rest of this schema family uses. This field is the branch tip. It does NOT mean what RepoStatus.base_sha means: there, base_sha is the last SHA the control plane pushed, deliberately not the tip, and external_change is defined as the two differing. Removal waits for a major version.
`files`	ConfigFile []	Yes

`head_sha`	string	No	The branch tip commit SHA. Matches RepoStatus.head_sha and RepoTreeEntries.head_sha.
The branch tip commit SHA. Matches RepoStatus.head_sha and RepoTreeEntries.head_sha.

Config File

type: ConfigFile

A single config file — repo-relative path and verbatim UTF-8 content.

Property	Type	Required	Description
`content`	string	Yes	The file’s verbatim UTF-8 content.
The file’s verbatim UTF-8 content.
`path`	string	Yes	Repo-relative path (e.g. “amfelt.yaml”, “contracts/aw.odcs.yaml”).
Repo-relative path (e.g. “amfelt.yaml”, “contracts/aw.odcs.yaml”).

Repo Status

type: RepoStatus

Working-copy (overlay) status against the committed config tree.

Property	Type	Required	Description
`base_sha`	string	No	The last SHA the control plane pushed (exec.project_environment.git_base_sha). Empty until the first commit.
The last SHA the control plane pushed (exec.project_environment.git_base_sha). Empty until the first commit.
`binding`	RepoBindingView	No

`dirty`	boolean	Yes	True when the authored overlay differs from the committed tree.
True when the authored overlay differs from the committed tree.
`external_change`	boolean	Yes	True when head_sha differs from base_sha — someone committed out-of-band (e.g. the CLI).
True when head_sha differs from base_sha — someone committed out-of-band (e.g. the CLI).
`files`	RepoStatusFile []	Yes	One entry per changed file. Empty when up to date.
One entry per changed file. Empty when up to date.
`head_sha`	string	No	Current branch HEAD SHA. Empty when the branch has no commits yet.
Current branch HEAD SHA. Empty when the branch has no commits yet.
`objects`	RepoStatusObject []	No	The changed objects, grouped from the same working copy the files array describes — both are projections of one diff, never two diffs. Absent when HEAD could not be parsed into job/object structure (e.g. an out-of-band commit left invalid YAML); files remains authoritative in that case.
The changed objects, grouped from the same working copy the files array describes — both are projections of one diff, never two diffs. Absent when HEAD could not be parsed into job/object structure (e.g. an out-of-band commit left invalid YAML); files remains authoritative in that case.

Repo Binding View

type: RepoBindingView

The non-secret view of a project-environment’s Git repo binding. The token is never returned.

Property	Type	Required	Description
`branch`	string	No	Target branch for this environment’s config.
Target branch for this environment’s config.
`display_name`	string	Yes	Human-readable repository name.
Human-readable repository name.
`git_repo_url`	string	Yes	HTTPS clone URL of the configuration repository.
HTTPS clone URL of the configuration repository.
`managed`	boolean	Yes	True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
True when the platform created the repository on its own git host (ADR-129 decision 11); false for a repository the customer connected. Read-only.
`status`	RepoBindingStatus	Yes

Repo Binding Status

type: RepoBindingStatus

The state of the environment’s repository. ready: the repository exists and is bound. pending: the platform is provisioning it, or the git host was unreachable and a retry is scheduled. failed: the git host refused the last attempt; the platform retries later, and an environment failed because the git host denied the tenant’s access three attempts in a row stays failed until a retry succeeds or an owner or admin asks for one. Runs answer 409 repository_required while the status is pending or failed. A scheduled run that falls due meanwhile is skipped, not queued: its schedule moves on to the next occurrence, and the skip is recorded in the tenant’s audit trail (actor system, action create on the job, outcome denied, reason repository_required).

Repo Status File

type: RepoStatusFile

Property	Type	Required	Description
`change`	string	Yes	How the file changed relative to the committed tree. Valid values are: `modified`, `added`, `deleted`.
How the file changed relative to the committed tree. Valid values are: `modified`, `added`, `deleted`.
`changed_by`	string	No	Display identity of the latest staging-area actor for this entry, resolved at read time (ADR-133): the account’s email address, or absent when the actor cannot be resolved. Absent also means no attribution is recorded — absence is never a claim.
Display identity of the latest staging-area actor for this entry, resolved at read time (ADR-133): the account’s email address, or absent when the actor cannot be resolved. Absent also means no attribution is recorded — absence is never a claim.
`changed_by_kind`	string	No	What kind of actor changed_by describes. “agent” rows have no email; “former_member” rows name an account no longer visible to the tenant. Absent when no attribution is recorded. Present without changed_by for agent and former_member, which carry no email. Valid values are: `account`, `agent`, `former_member`.
What kind of actor changed_by describes. “agent” rows have no email; “former_member” rows name an account no longer visible to the tenant. Absent when no attribution is recorded. Present without changed_by for agent and former_member, which carry no email. Valid values are: `account`, `agent`, `former_member`.
`conflicted`	boolean	No	True when this file changed at HEAD since the editing base, so committing it would overwrite another writer (ADR-119 as revised). Optional: present only for files the api can give a verdict on — today the contract files under contracts/. Absent means no verdict, NOT “safe”; a client must not read an absent value as permission.
True when this file changed at HEAD since the editing base, so committing it would overwrite another writer (ADR-119 as revised). Optional: present only for files the api can give a verdict on — today the contract files under contracts/. Absent means no verdict, NOT “safe”; a client must not read an absent value as permission.
`path`	string	Yes	Repo-relative path (e.g. “amfelt.yaml”, “contracts/aw.odcs.yaml”).
Repo-relative path (e.g. “amfelt.yaml”, “contracts/aw.odcs.yaml”).
`rows`	DiffRow []	Yes	Line-aligned diff rows for rendering side-by-side or unified.
Line-aligned diff rows for rendering side-by-side or unified.

Diff Row

type: DiffRow

Property	Type	Required	Description
`left`	string	No	The line as it appears in git (committed). Empty for insert.
The line as it appears in git (committed). Empty for insert.
`op`	string	Yes	equal = unchanged line on both sides; insert = added on the right; delete = removed from the left. Valid values are: `equal`, `insert`, `delete`.
equal = unchanged line on both sides; insert = added on the right; delete = removed from the left. Valid values are: `equal`, `insert`, `delete`.
`right`	string	No	The line as authored now (overlay). Empty for delete.
The line as authored now (overlay). Empty for delete.

Repo Status Object

type: RepoStatusObject

One domain object with uncommitted changes. Objects are the unit a user selects when committing; files are the unit git stores. An object’s change lives entirely in amfelt.yaml unless it is newly added, in which case its source’s contract is carried too.

Property	Type	Required	Description
`change`	string	Yes	How the object changed relative to the committed tree. Valid values are: `added`, `modified`, `removed`.
How the object changed relative to the committed tree. Valid values are: `added`, `modified`, `removed`.
`changed_by`	string	No	Display identity of the latest staging-area actor for this entry, resolved at read time (ADR-133): the account’s email address, or absent when the actor cannot be resolved. Absent also means no attribution is recorded — absence is never a claim.
Display identity of the latest staging-area actor for this entry, resolved at read time (ADR-133): the account’s email address, or absent when the actor cannot be resolved. Absent also means no attribution is recorded — absence is never a claim.
`changed_by_kind`	string	No	What kind of actor changed_by describes. “agent” rows have no email; “former_member” rows name an account no longer visible to the tenant. Absent when no attribution is recorded. Present without changed_by for agent and former_member, which carry no email. Valid values are: `account`, `agent`, `former_member`.
What kind of actor changed_by describes. “agent” rows have no email; “former_member” rows name an account no longer visible to the tenant. Absent when no attribution is recorded. Present without changed_by for agent and former_member, which carry no email. Valid values are: `account`, `agent`, `former_member`.
`conflicted`	boolean	Yes	True when this object’s committed projection changed at HEAD since the editing base, so committing it would overwrite another writer.
True when this object’s committed projection changed at HEAD since the editing base, so committing it would overwrite another writer.
`files`	string[]	Yes	Repo-relative paths this object’s change touches.
Repo-relative paths this object’s change touches.
`job`	string	Yes	The job this object belongs to.
The job this object belongs to.
`name`	string	Yes	The object’s name within the job’s selection.
The object’s name within the job’s selection.
`summary`	string	No	Plain-English description of what changed, for display. Absent when no summary could be derived; clients must not depend on its wording.
Plain-English description of what changed, for display. Absent when no summary could be derived; clients must not depend on its wording.

SQL Render Result

type: SqlRenderResult

Property	Type	Required	Description
`command_id`	string	Yes	The command_id from the cmd.render_sql frame this answers.
The command_id from the cmd.render_sql frame this answers.
`error`	string	No	Why the render failed. Required when status is failed.
Why the render failed. Required when status is failed.
`objects`	SqlRenderedObject []	No

`plugin_version`	string	No	The plugin@version that produced this render, as core/sql stamps into every header.
The plugin@version that produced this render, as core/sql stamps into every header.
`ref`	string	Yes	The commit SHA the agent actually rendered.
The commit SHA the agent actually rendered.
`status`	string	Yes	rendered means objects is authoritative and MAY legitimately be empty, which prunes the tree. failed means the render did not complete and objects must be ignored entirely. These are distinct because an empty object list is a valid render outcome, so a caller cannot infer failure from it. Valid values are: `rendered`, `failed`.
rendered means objects is authoritative and MAY legitimately be empty, which prunes the tree. failed means the render did not complete and objects must be ignored entirely. These are distinct because an empty object list is a valid render outcome, so a caller cannot infer failure from it. Valid values are: `rendered`, `failed`.

SQL Rendered Object

type: SqlRenderedObject

Property	Type	Required	Description
`layers`	object	Yes	Rendered SQL keyed by layer — staging, history, bridge, historize. A layer the job does not run is absent, never present and empty.
Rendered SQL keyed by layer — staging, history, bridge, historize. A layer the job does not run is absent, never present and empty.
`name`	string	Yes	Object name. Becomes the second path segment.
Object name. Becomes the second path segment.
`namespace`	string	Yes	Source name the object was rendered for. Becomes the first path segment under sql/.
Source name the object was rendered for. Becomes the first path segment under sql/.

SQL Render Ingest Result

type: SqlRenderIngestResult

The result of ingesting a rendered generated-SQL tree.

Property	Type	Required	Description
`commit_sha`	string	Yes	The created commit SHA. Empty when the commit was a no-op (no changes to push).
The created commit SHA. Empty when the commit was a no-op (no changes to push).
`files`	string[]	Yes	Repo-relative paths written by the commit.
Repo-relative paths written by the commit.
`outcome`	string	Yes	What the ingest actually did with the render. committed means a follow-up commit landed. no_change means the result was accepted and there was nothing to commit. discarded_stale means the render described a commit that is no longer the branch tip, so it was discarded — nothing re-dispatches it, which is why this outcome exists to surface: a discarded render is otherwise silent. Valid values are: `committed`, `no_change`, `discarded_stale`.
What the ingest actually did with the render. committed means a follow-up commit landed. no_change means the result was accepted and there was nothing to commit. discarded_stale means the render described a commit that is no longer the branch tip, so it was discarded — nothing re-dispatches it, which is why this outcome exists to surface: a discarded render is otherwise silent. Valid values are: `committed`, `no_change`, `discarded_stale`.

Repo Restore Request

type: RepoRestoreRequest

Property	Type	Required	Description
`ref`	string	Yes	Commit SHA to restore the job graph to. Required, and a commit SHA rather than a branch or tag name: a name that is not a well-formed hash is rejected the same way an absent commit is. Unlike the import request, an empty value is not accepted as “the branch tip” — this operation deletes jobs, so the tip must be named explicitly to be chosen.
Commit SHA to restore the job graph to. Required, and a commit SHA rather than a branch or tag name: a name that is not a well-formed hash is rejected the same way an absent commit is. Unlike the import request, an empty value is not accepted as “the branch tip” — this operation deletes jobs, so the tip must be named explicitly to be chosen.

Repo Restore Result

type: RepoRestoreResult

Property	Type	Required	Description
`head_sha`	string	Yes	The branch tip at the time of the restore, which may be ahead of the restored ref.
The branch tip at the time of the restore, which may be ahead of the restored ref.
`reconciled_sha`	[string null]	No	The editing base after the restore. Unchanged by this operation; reported so a client need not re-read status.
The editing base after the restore. Unchanged by this operation; reported so a client need not re-read status.
`removed_jobs`	string[]	Yes	Names of jobs deleted because ref does not carry them, in sorted order. Their runs and any derived scheduling state were deleted with them.
Names of jobs deleted because ref does not carry them, in sorted order. Their runs and any derived scheduling state were deleted with them.
`restored_contracts`	string[]	Yes	Repo-relative paths of contract documents written, in sorted order.
Repo-relative paths of contract documents written, in sorted order.
`restored_jobs`	string[]	Yes	Names of jobs written, in sorted order.
Names of jobs written, in sorted order.
`restored_objects`	RepoImportObject []	Yes	The (job, object) pairs the restored graph selects, echoed so a client can confirm coverage.
The (job, object) pairs the restored graph selects, echoed so a client can confirm coverage.

Repo Import Object

type: RepoImportObject

Property	Type	Required	Description
`job`	string	Yes	Name of the job the object belongs to.
Name of the job the object belongs to.
`name`	string	Yes	Object name as it appears in the job’s selection.
Object name as it appears in the job’s selection.

Push Config Request

type: PushConfigRequest

Agent-supplied config files to commit, guarded by the caller’s base SHA.

Property	Type	Required	Description
`base_sha`	string	Yes	The caller’s last-seen commit SHA. Empty on a first commit; a mismatch with the branch HEAD returns 409.
The caller’s last-seen commit SHA. Empty on a first commit; a mismatch with the branch HEAD returns 409.
`files`	ConfigFile []	Yes

Push Config Result

type: PushConfigResult

The result of a git-lite push.

Property	Type	Required	Description
`commit_sha`	string	Yes	The created commit SHA. Empty when the push was a no-op.
The created commit SHA. Empty when the push was a no-op.

Repo Import Request

type: RepoImportRequest

Property	Type	Required	Description
`objects`	RepoImportObject []	Yes	The objects to make match ref. An object absent at ref is removed from the staging area.
The objects to make match ref. An object absent at ref is removed from the staging area.
`ref`	string	No	Commit SHA to import from. Omitted or empty means the branch tip, matching the repo tree read. A branch or tag name is not accepted.
Commit SHA to import from. Omitted or empty means the branch tip, matching the repo tree read. A branch or tag name is not accepted.

Repo Import Result

type: RepoImportResult

Property	Type	Required	Description
`head_sha`	string	Yes	The branch tip at the time of the import, which may be ahead of ref.
The branch tip at the time of the import, which may be ahead of ref.
`imported_objects`	RepoImportObject []	Yes	The objects written, echoed back so a client can confirm what the import covered.
The objects written, echoed back so a client can confirm what the import covered.
`reconciled_sha`	[string null]	No	The editing base after the import. Unchanged by this operation; reported so a client need not re-read status.
The editing base after the import. Unchanged by this operation; reported so a client need not re-read status.

Repo File

type: RepoFile

One file’s committed content, or a stated reason it cannot be shown.

Property	Type	Required	Description
`content`	string	No	The file’s verbatim UTF-8 content. Absent when unavailable_reason is set. Never truncated — a partial file a user cannot distinguish from the whole one is the outcome this field’s absence exists to prevent.
The file’s verbatim UTF-8 content. Absent when unavailable_reason is set. Never truncated — a partial file a user cannot distinguish from the whole one is the outcome this field’s absence exists to prevent.
`path`	string	Yes	Repo-relative path, echoing the request.
Repo-relative path, echoing the request.
`ref`	string	Yes	The commit the content was read at.
The commit the content was read at.
`size`	integer	Yes	Size in bytes.
Size in bytes.
`unavailable_reason`	string	No	Why content is absent. Absent itself when the file was returned. A client must render the reason rather than an empty file. Valid values are: `too_large`, `not_utf8`.
Why content is absent. Absent itself when the file was returned. A client must render the reason rather than an empty file. Valid values are: `too_large`, `not_utf8`.

Repo Commits

type: RepoCommits

A page of the bound branch’s first-parent history, newest first.

Property	Type	Required	Description
`commits`	RepoCommit []	Yes	One entry per commit. Empty when the branch has no commits yet.
One entry per commit. Empty when the branch has no commits yet.
`head_sha`	string	Yes	The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
The branch tip at the time of the read, which differs from ref when the caller pinned an older commit. Compare against a previously seen value to detect that the branch has moved.
`next_ref`	string	No	The commit to pass as ref to fetch the next page. ABSENT when the walk reached the root commit — which is how a client tells “this is the beginning” from “ask again”, without comparing counts to a limit it may not have set.
The commit to pass as ref to fetch the next page. ABSENT when the walk reached the root commit — which is how a client tells “this is the beginning” from “ask again”, without comparing counts to a limit it may not have set.
`ref`	string	Yes	The commit the walk started at. Echoed back so a client can pin a page and cache it — every page below the branch tip is immutable.
The commit the walk started at. Echoed back so a client can pin a page and cache it — every page below the branch tip is immutable.

Repo Commit

type: RepoCommit

One commit’s metadata. Never carries file content.

Property	Type	Required	Description
`author_email`	string	No	The author email recorded in the commit. Unverified, as author_name.
The author email recorded in the commit. Unverified, as author_name.
`author_name`	string	Yes	The author recorded in the commit. This is git’s own field and is NOT verified by the platform — a commit pushed out-of-band carries whatever that user’s git configuration said. Display it as reported; never present it as an assertion of identity.
The author recorded in the commit. This is git’s own field and is NOT verified by the platform — a commit pushed out-of-band carries whatever that user’s git configuration said. Display it as reported; never present it as an assertion of identity.
`changed_paths`	string[]	Yes	Repo-relative paths this commit changed against its first parent, so a list row can show a file count without a second request. Read the diff endpoint for content.
Repo-relative paths this commit changed against its first parent, so a list row can show a file count without a second request. Read the diff endpoint for content.
`message`	string	Yes	The full commit message. The first line is the subject; anything after it is the body.
The full commit message. The first line is the subject; anything after it is the body.
`parent_sha`	string	No	The FIRST parent’s SHA. Absent at the root commit. A merge commit’s second parent is not reported: this endpoint walks first parents.
The FIRST parent’s SHA. Absent at the root commit. A merge commit’s second parent is not reported: this endpoint walks first parents.
`sha`	string	Yes	The commit SHA.
The commit SHA.
`when`	string	Yes	The commit’s author timestamp.
The commit’s author timestamp.

Repo Commit Diff

type: RepoCommitDiff

One commit’s changes against its first parent, as line-aligned rows. Distinct from RepoStatus, which diffs the working copy against HEAD and carries a conflict verdict this schema deliberately has no concept of.

Property	Type	Required	Description
`files`	RepoCommitDiffFile []	Yes	One entry per changed path. A path the commit did not touch is absent, never present with an empty row list.
One entry per changed path. A path the commit did not touch is absent, never present with an empty row list.
`parent_sha`	string	No	The first parent the diff was taken against. Absent at the root commit, where every path reads as added.
The first parent the diff was taken against. Absent at the root commit, where every path reads as added.
`ref`	string	Yes	The commit that was diffed.
The commit that was diffed.

Repo Commit Diff File

type: RepoCommitDiffFile

Property	Type	Required	Description
`change`	string	Yes	How this commit changed the path relative to its first parent. Valid values are: `modified`, `added`, `deleted`.
How this commit changed the path relative to its first parent. Valid values are: `modified`, `added`, `deleted`.
`path`	string	Yes	Repo-relative path.
Repo-relative path.
`refused_reason`	string	No	Present when the file could not be diffed, in place of rows. The other files in the same commit still carry theirs — one oversized file never suppresses a whole commit’s diff. Valid values are: `too_large`, `not_utf8`.
Present when the file could not be diffed, in place of rows. The other files in the same commit still carry theirs — one oversized file never suppresses a whole commit’s diff. Valid values are: `too_large`, `not_utf8`.
`rows`	DiffRow []	No	Line-aligned diff rows. Absent when refused_reason is set.
Line-aligned diff rows. Absent when refused_reason is set.

Repo Commit Request

type: RepoCommitRequest

User-supplied commit metadata for a config commit. base_sha gives optimistic concurrency; when empty the stored base SHA is used.

Property	Type	Required	Description
`base_sha`	string	No	The HEAD SHA the user reviewed against. When non-empty and it no longer matches the branch HEAD, the commit returns 409. When empty, the stored git_base_sha is used.
The HEAD SHA the user reviewed against. When non-empty and it no longer matches the branch HEAD, the commit returns 409. When empty, the stored git_base_sha is used.
`contracts`	string[]	No	Contract files to include, as repo-relative paths exactly as given on RepoStatusFile.path (e.g. “contracts/sales.odcs.yaml”). A contract is a whole-file unit (ADR-093 §6) — it commits entirely or not at all, never a subset of its content. Identified by path rather than by a job/name pair, because a contract belongs to a source rather than to an object. Omitted or empty commits no contract change, which is what an objects-only selection means; omitting BOTH objects and contracts is the whole-set commit.
Contract files to include, as repo-relative paths exactly as given on RepoStatusFile.path (e.g. “contracts/sales.odcs.yaml”). A contract is a whole-file unit (ADR-093 §6) — it commits entirely or not at all, never a subset of its content. Identified by path rather than by a job/name pair, because a contract belongs to a source rather than to an object. Omitted or empty commits no contract change, which is what an objects-only selection means; omitting BOTH objects and contracts is the whole-set commit.
`message`	string	No	Commit message. When blank, the control plane supplies a default.
Commit message. When blank, the control plane supplies a default.
`objects`	RepoObjectRef []	No	Objects to include, identified by job + name as given on each RepoStatusObject. Omitted or empty selects no object; omitting BOTH objects and contracts is the whole-set commit — the pre-existing behavior, so an older client is unaffected.
Objects to include, identified by job + name as given on each RepoStatusObject. Omitted or empty selects no object; omitting BOTH objects and contracts is the whole-set commit — the pre-existing behavior, so an older client is unaffected.

Repo Object Ref

type: RepoObjectRef

A reference to a domain object, identified the same way RepoStatusObject is: job + name. Two jobs may select an identically-named object from different sources, so the pair is the identity — neither field alone is unique.

Property	Type	Required	Description
`job`	string	Yes	The job the object belongs to.
The job the object belongs to.
`name`	string	Yes	The object’s name within the job’s selection.
The object’s name within the job’s selection.

Repo Commit Result

type: RepoCommitResult

The result of committing the environment’s contract(s) to Git.

Property	Type	Required	Description
`commit_sha`	string	Yes	The created commit SHA. Empty when the commit was a no-op (no changes to push).
The created commit SHA. Empty when the commit was a no-op (no changes to push).
`files`	string[]	Yes	Repo-relative paths written by the commit.
Repo-relative paths written by the commit.

Repo Binding

type: RepoBinding

Connect or update a project-environment’s Git repository binding. The token is write-only.

Property	Type	Required	Description
`branch`	string	No	Target branch for this environment’s config. Defaults to ‘main’ when omitted.
Target branch for this environment’s config. Defaults to ‘main’ when omitted.
`display_name`	string	Yes	Human-readable repository name.
Human-readable repository name.
`git_repo_url`	string	Yes	HTTPS clone URL of the configuration repository.
HTTPS clone URL of the configuration repository.
`token`	string	No	Personal access token (PAT) for git-over-HTTPS. Write-only; omit or send blank to keep the existing token (ADR-056 merge rule). Never returned on read.
Personal access token (PAT) for git-over-HTTPS. Write-only; omit or send blank to keep the existing token (ADR-056 merge rule). Never returned on read.

Catalog Source List

type: CatalogSourceList

A project environment’s catalog sources.

Property	Type	Required	Description
`data`	CatalogSource []	Yes	The catalog sources.
The catalog sources.

Catalog Source

type: CatalogSource

A discovered catalog source (or target) — the list-view projection of a stored ODCS contract.

Property	Type	Required	Description
`description`	string	No	Short description.
Short description.
`id`	string	Yes	Catalog source slug.
Catalog source slug.
`name`	string	Yes	Source display name.
Source display name.
`plugin`	string	No	Plugin key (e.g. postgres, snowflake).
Plugin key (e.g. postgres, snowflake).
`role`	string	Yes	Whether the asset is an inbound source or the outbound target. Valid values are: `source`, `target`.
Whether the asset is an inbound source or the outbound target. Valid values are: `source`, `target`.

Doc Notes

type: DocNotes

The authored prose on one catalog page.

Property	Type	Required	Description
`notes`	DocNote []	Yes	One entry per protected region on the page, ordered by region name. Empty when the page carries no prose, when the project has documentation disabled, or when nothing has been committed yet — all three render identically, as nothing.
One entry per protected region on the page, ordered by region name. Empty when the page carries no prose, when the project has documentation disabled, or when nothing has been committed yet — all three render identically, as nothing.

Doc Note

type: DocNote

One protected region’s authored prose.

Property	Type	Required	Description
`body`	string	Yes	The authored prose, verbatim, without the marker comments.
The authored prose, verbatim, without the marker comments.
`page_path`	string	Yes	Repo-relative path of the documentation page this prose was read from. Shown to the reader as its origin, so authored notes cannot be mistaken for derived truth. Examples: `docs/sources/adventureworks/sales/customer.md`.
Repo-relative path of the documentation page this prose was read from. Shown to the reader as its origin, so authored notes cannot be mistaken for derived truth. Examples: `docs/sources/adventureworks/sales/customer.md`.
`region_name`	string	Yes	The protected region’s name, e.g. “notes”. Examples: `notes`.
The protected region’s name, e.g. “notes”. Examples: `notes`.
`source_commit_sha`	string	Yes	The commit the prose was parsed from. It may lag the contract the page describes, because documentation generation never blocks a configuration commit.
The commit the prose was parsed from. It may lag the contract the page describes, because documentation generation never blocks a configuration commit.
`updated_at`	string	Yes	When this projection was last written.
When this projection was last written.

Pause Schedule Request

type: PauseScheduleRequest

The payload for pausing one scheduled entry of a job.

Property	Type	Required	Description
`reason`	string	Yes	Why the entry is paused, shown with the paused state. Examples: `source maintenance`.
Why the entry is paused, shown with the paused state. Examples: `source maintenance`.

Object Advice List

type: ObjectAdviceList

A catalog source’s object-level advice recommendations.

Property	Type	Required	Description
`data`	ObjectAdvice []	Yes	The object-level advice recommendations.
The object-level advice recommendations.

Object Advice

type: ObjectAdvice

One object’s LLM-advisor recommendation — table type, provider/model provenance, and when it was advised.

Property	Type	Required
`advised_at`	string	No

`advisor_model`	string	No

`advisor_provider`	string	No

`object_name`	string	Yes

`recommended_table_type`	string	No

History Rebuild List

type: HistoryRebuildList

The pending history rebuilds of one catalog source, at most one per object and target, oldest requested_at first. A completed or canceled rebuild is never listed.

Property	Type	Required	Description
`data`	HistoryRebuild []	Yes

History Rebuild

type: HistoryRebuild

A confirmed request to rebuild one object’s history on one target after its history mode changed, recorded by the api’s history-mode guard on one of its four writes (HistoryRebuildConflict). Two jobs that load the same object to different targets get one record each. An object has at most one pending rebuild per target: a newer confirmed change cancels it and records its own, and a change back to the built mode cancels it.

Which run acts on a pending rebuild: only a run that loads the object to the rebuild’s target and resolves the object’s history mode to new_history_mode. That run drops the object’s history and dependent bridge on that target, rebuilds them from current staging in new_history_mode, and reports the rebuild with completeHistoryRebuild. A run that resolves the object to another history mode (its configuration predates the change) drops nothing and leaves the rebuild pending: in the built mode it loads the history as before, and in any other mode the run-time refusal applies (HistoryRebuildConflict). A run that does not load the rebuild’s target leaves it as it is.

Property	Type	Required	Description
`canceled_at`	string	No	When a newer confirmed change or a change back to the built mode canceled the rebuild; set exactly when status is canceled.
When a newer confirmed change or a change back to the built mode canceled the rebuild; set exactly when status is canceled.
`completed_at`	string	No	When a run reported the rebuild done; set exactly when status is completed.
When a run reported the rebuild done; set exactly when status is completed.
`completed_run_id`	integer	No	The run that rebuilt the history; set exactly when status is completed. A repeat of completeHistoryRebuild with this run_id answers the record unchanged.
The run that rebuilt the history; set exactly when status is completed. A repeat of completeHistoryRebuild with this run_id answers the record unchanged.
`environment`	string	Yes	DTAP environment slug.
DTAP environment slug.
`history_mode`	string	Yes	The history mode the existing history was built in: the mode the guard compared against. As HistoryModeChange.history_mode. Examples: `scd1`.
The history mode the existing history was built in: the mode the guard compared against. As HistoryModeChange.history_mode. Examples: `scd1`.
`id`	string	Yes

`new_history_mode`	string	Yes	The history mode to rebuild in; never equal to history_mode. As HistoryModeChange.new_history_mode. Examples: `scd2`.
The history mode to rebuild in; never equal to history_mode. As HistoryModeChange.new_history_mode. Examples: `scd2`.
`object_name`	string	Yes	The schema object’s ODCS name (schema[].name).
The schema object’s ODCS name (schema[].name).
`project_id`	string	Yes

`requested_at`	string	Yes

`requested_by`	string	Yes	The id of what confirmed the rebuild: the account of the person who confirmed it (requested_by_type account).
The id of what confirmed the rebuild: the account of the person who confirmed it (requested_by_type account).
`requested_by_type`	HistoryRebuildRequesterType	Yes

`source_slug`	string	Yes

`status`	HistoryRebuildStatus	Yes

`target`	string	Yes	The target platform slug whose history is rebuilt: the job’s target, or the environment’s platform when the job names none (Job.target).
The target platform slug whose history is rebuilt: the job’s target, or the environment’s platform when the job names none (Job.target).

History Rebuild Requester Type

type: HistoryRebuildRequesterType

What confirmed a history rebuild. account: a person, through one of the four writes the api’s history-mode guard applies to (HistoryRebuildConflict), which are all user-authenticated, so every rebuild this contract records is account. agent: reserved for a confirmation an agent sends; no operation in this contract records one, since no agent-sent write is guarded.

History Rebuild Status

type: HistoryRebuildStatus

pending (confirmed; the next run of the object drops its history and dependent bridge and rebuilds them from current staging in the new mode) or completed (a run did). A pending rebuild becomes canceled instead when a newer confirmed change supersedes it, or when a change back to the mode the history was built in makes it unnecessary, each through one of the guarded writes (HistoryRebuildConflict); no run acts on a canceled rebuild. completed and canceled are final. HistoryRebuild says exactly which run acts on a pending rebuild.

Schema Drift Event

type: SchemaDriftEvent

A recorded source schema-drift event (CAP-01-03) — one per ingest whose re-harvested contract differed from the stored baseline.

Property	Type	Required	Description
`created_at`	string	Yes

`drift_record`	object	Yes	The full drift.DriftRecord (verdicts, overall bump, ruleset + lattice versions).
The full drift.DriftRecord (verdicts, overall bump, ruleset + lattice versions).
`environment`	string	Yes	DTAP environment slot.
DTAP environment slot.
`id`	string	Yes

`overall_bump`	string	Yes	Rolled-up semver bump across all detected changes. Valid values are: `patch`, `minor`, `major`.
Rolled-up semver bump across all detected changes. Valid values are: `patch`, `minor`, `major`.
`source_slug`	string	Yes	Catalog source slug that drifted.
Catalog source slug that drifted.

Catalog Contract

type: CatalogContract

A source’s ODCS v3 data contract, verbatim.

Property	Type	Required	Description
`contract_yaml`	string	Yes	The ODCS v3 contract document, verbatim YAML.
The ODCS v3 contract document, verbatim YAML.
`created_at`	string	Yes	Timestamp the contract document was first harvested.
Timestamp the contract document was first harvested.
`updated_at`	string	Yes	Timestamp the contract document was last re-harvested; every metadata ingest bumps it, so the app can detect re-discovery completion and show a DB-accurate last-discovery time.
Timestamp the contract document was last re-harvested; every metadata ingest bumps it, so the app can detect re-discovery completion and show a DB-accurate last-discovery time.

Put Catalog Contract Request

type: PutCatalogContractRequest

Upsert a source’s ODCS contract plus its denormalized list fields.

Property	Type	Required	Description
`contract_yaml`	string	Yes	The ODCS v3 contract document, verbatim YAML.
The ODCS v3 contract document, verbatim YAML.
`description`	string	No	Short description.
Short description.
`name`	string	No	Source display name.
Source display name.
`plugin`	string	No

`role`	string	No	Valid values are: `source`, `target`.
Valid values are: `source`, `target`.

Catalog Classifications

type: CatalogClassifications

A catalog source’s table classifications and PII labels.

Property	Type	Required
`objects`	ObjectClassification []	Yes

`pii`	PiiLabel []	Yes

Object Classification

type: ObjectClassification

The table classification of one schema object.

Property	Type	Required	Description
`approved_at`	string	No	When the classification was approved, or last changed: a change (changeProjectCatalogObjectClassification) records its own time.
When the classification was approved, or last changed: a change (changeProjectCatalogObjectClassification) records its own time.
`approved_by`	string	No	Who approved the classification, or last changed it: the person who approved it (approveProjectCatalogObjectClassification) or changed it (changeProjectCatalogObjectClassification), or the literal advisor for an auto-approval verified against the advisor call it names (ingestCatalogClassifications). No other write sets it (ClassificationStatus). An auto-applied classification can be changed like any approved one; the change applies from the next run.
Who approved the classification, or last changed it: the person who approved it (approveProjectCatalogObjectClassification) or changed it (changeProjectCatalogObjectClassification), or the literal advisor for an auto-approval verified against the advisor call it names (ingestCatalogClassifications). No other write sets it (ClassificationStatus). An auto-applied classification can be changed like any approved one; the change applies from the next run.
`business_key`	string[]	No

`confidence`	number	No

`history_mode`	string	No

`history_rebuilds`	HistoryRebuild []	No	The object’s pending history rebuilds, at most one per target; empty or absent when none is pending. A completed or canceled rebuild is not listed.
The object’s pending history rebuilds, at most one per target; empty or absent when none is pending. A completed or canceled rebuild is not listed.
`object_name`	string	Yes

`proposed_at`	string	No

`proposed_by`	string	No

`status`	ClassificationStatus	Yes

`table_type`	string	Yes

`transactional`	boolean	Yes

Classification Status

type: ClassificationStatus

proposed (an algorithm suggested it) or approved (a person confirmed it, or the advisor applied it with confidence). Only an approval moves a classification to approved (ADR-159, Decision 4); an auto-approval is the advisor’s approval, filed by the agent with proposed_by advisor and read back with approved_by advisor.

Classification state has one owner. Classification state is each object’s table classification (its status, values, confidence, proposed_by, proposed_at, approved_by and approved_at) and each property’s PII label (its status, label, confidence, method, proposed_at, approved_by and approved_at), together with the property’s ODCS classification field (schema[].properties[].classification), which an approved PII label sets. It changes only through these operations, which own it: ingestCatalogClassifications (a proposal, or an auto-approval verified against the advisor call it names), and approveProjectCatalogObjectClassification, changeProjectCatalogObjectClassification, rejectProjectCatalogObjectClassification, approveProjectCatalogPiiLabel and rejectProjectCatalogPiiLabel. No contract or configuration write sets it: putProjectCatalogContract, ingestCatalogContract, postProjectEnvironmentRepoPush, postProjectEnvironmentRepoImport, postProjectEnvironmentRepoRestore, putProjectEnvironmentRepo and moveProjectRepository among them. Such a write ignores the classification and PII-label state inline in any contract or configuration it carries or takes from a repository, proposed or approved, a property’s ODCS classification field included.

The api carries stored state over by object and property identity, an object or property a write drops included. An object’s identity is its project, environment, source and ODCS name (schema[].name); a property’s is its object and its ODCS name (schema[].properties[].name). A write that drops an object or a property leaves its stored state in place, and when a later write brings the same object or property back, the api restores that state on it. An object or property that has no stored state gets none. Each such write says so with the words “the stored state is carried over (ClassificationStatus)”.

Pii Label

type: PiiLabel

The PII label of one property.

Property	Type	Required	Description
`approved_at`	string	No

`approved_by`	string	No

`classification`	string	No	The property’s ODCS classification field, set on approval.
The property’s ODCS classification field, set on approval.
`confidence`	number	Yes

`label`	string	Yes

`method`	string	Yes

`object_name`	string	Yes

`property_name`	string	Yes

`proposed_at`	string	Yes

`status`	ClassificationStatus	Yes

Catalog Object Activity

type: CatalogObjectActivity

What the runs have landed for one catalog object.

Property	Type	Required	Description
`last_load`	CatalogObjectLastLoad	No

`layers`	CatalogObjectLayerActivity []	Yes	The object’s tasks in its most recent run, one per warehouse layer.
The object’s tasks in its most recent run, one per warehouse layer.
`lifetime`	CatalogObjectLifetime	Yes

`object_id`	string	Yes	Namespace-qualified object key, e.g. “public.customer”. Matches exec.task.object_id. Examples: `public.customer`.
Namespace-qualified object key, e.g. “public.customer”. Matches exec.task.object_id. Examples: `public.customer`.
`waiting`	ObjectWaitReason	No

Catalog Object Last Load

type: CatalogObjectLastLoad

The most recent run that touched this object.

Property	Type	Required	Description
`at`	string	No	When the object’s last task in that run finished. Absent when the run has not finished.
When the object’s last task in that run finished. Absent when the run has not finished.
`run_id`	integer	Yes	The run’s identifier.
The run’s identifier.
`status`	string	Yes	The run’s status, verbatim — a failed last load must read as failed, not be hidden. Examples: `finished`.
The run’s status, verbatim — a failed last load must read as failed, not be hidden. Examples: `finished`.

Catalog Object Layer Activity

type: CatalogObjectLayerActivity

One warehouse layer’s outcome for the object, in its most recent run.

Property	Type	Required	Description
`duration_ms`	integer	No	How long the task took.
How long the task took.
`layer`	string	Yes	Warehouse layer. Examples: `staging`.
Warehouse layer. Examples: `staging`.
`rows`	integer	Yes	Rows the run reported processing into this layer (rows_processed). Zero is not failure — an idempotent SCD2 merge that finds nothing changed correctly writes zero history rows, and the caller renders that as “no changes”.
Rows the run reported processing into this layer (rows_processed). Zero is not failure — an idempotent SCD2 merge that finds nothing changed correctly writes zero history rows, and the caller renders that as “no changes”.
`skip_reason`	string	No	Set when the most recent run deliberately did not run this layer for the object, with the reason as the agent reported it, for example “no history: awaiting classification”. Absent when the layer ran, or when the run did not report a reason.
Set when the most recent run deliberately did not run this layer for the object, with the reason as the agent reported it, for example “no history: awaiting classification”. Absent when the layer ran, or when the run did not report a reason.
`status`	string	Yes	The task’s status. Examples: `ok`.
The task’s status. Examples: `ok`.

Catalog Object Lifetime

type: CatalogObjectLifetime

Totals across every run for the object, of any status.

Property	Type	Required	Description
`conflict`	integer	Yes	Source-side modifications to data the warehouse treats as immutable. The agent reports these; until OB-24 the api discarded them. A non-zero value is the first thing anything has ever been able to alert on.
Source-side modifications to data the warehouse treats as immutable. The agent reports these; until OB-24 the api discarded them. A non-zero value is the first thing anything has ever been able to alert on.
`inserted`	integer	Yes

`updated`	integer	Yes

Object Wait Reason

type: ObjectWaitReason

Why a run loaded an object to staging and stopped there, waiting on its classification. Exactly three values, so a client never parses a skip_reason text. awaiting_approval: a proposed classification waits for a person, because the advisor was unsure. awaiting_rebuild_confirmation: the object’s history already exists on a target in another history mode than the run resolves it to, and a person must confirm a history rebuild (approve or change the classification, or save the job, with rebuild_history); this covers an auto-approval held for a rebuild (held_for_rebuild), and it is the value an agent reports for the run-time refusal (HistoryRebuildConflict). The other history mode is the built mode listHistoryStates lists; an object with none listed on that target never waits with this value: its run adopts the history mode it resolves, reports it, and is not refused. awaiting_classification: there is no classification yet, because the advisor gave no answer (own key failed, allowance used up, no provider, or an outage). A disabled advisor never makes an object wait. Set on a task or an object only when it waits; absent otherwise.

Catalog Profile

type: CatalogProfile

One stored profile of one schema object, with its body.

Child elements:

CatalogProfileSummary

Catalog Profile Summary

type: CatalogProfileSummary

One stored profile of one schema object, without its body.

Property	Type	Required	Description
`contract_version`	string	Yes	The version field of the stored contract the profile is linked to.
The version field of the stored contract the profile is linked to.
`created_at`	string	Yes

`exact`	boolean	Yes

`id`	string	Yes

`mode`	ProfileMode	Yes

`object_name`	string	Yes

`profiled_at`	string	Yes

`run_id`	[integer null]	No

Profile Mode

type: ProfileMode

full (every row was profiled), sample (a sample was), or delta (only the rows an incremental load brought). Only full is produced today.

Catalog Profile List

type: CatalogProfileList

Profiles of one schema object, newest first.

Property	Type	Required	Description
`data`	CatalogProfileSummary []	Yes

Object Classification Approval

type: ObjectClassificationApproval

Values that replace the proposed ones before approval, or the approved ones on a change. All optional.

Property	Type	Required	Description
`business_key`	string[]	No

`history_mode`	string	No

`rebuild_history`	boolean	No	Confirms that a history-mode change may drop the history the object already has on a target; the next run rebuilds it from current staging in the new mode. Without it, such a change answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when the history mode does not change or the object has no history yet.
Confirms that a history-mode change may drop the history the object already has on a target; the next run rebuilds it from current staging in the new mode. Without it, such a change answers 409 history_rebuild_required and changes nothing. Where the api knows no built mode for an object on a target, no 409 is answered for it and no rebuild is recorded there: the next run adopts the history mode it resolves and reports it, and that run is not refused (HistoryRebuildConflict). History loaded before the api recorded built modes cannot be verified. Ignored when the history mode does not change or the object has no history yet.
`table_type`	string	No

`transactional`	boolean	No

Pii Label Approval

type: PiiLabelApproval

Property	Type	Required	Description
`classification`	string	Yes	The ODCS classification to set on the property, for example restricted or confidential.
The ODCS classification to set on the property, for example restricted or confidential.
`label`	string	No	A label that replaces the proposed one before approval.
A label that replaces the proposed one before approval.

Last updated on October 31, 2026

Docs

projects

GET /v1/table-types

Responses

Security

GET /v1/projects

Parameters

Responses

Security

POST /v1/projects

Request body (required)

Responses

Security

GET /v1/environments

Responses

Security

POST /v1/projects/{id}/unarchive

Parameters

Responses

Security

GET /v1/projects/{id}/sources

Parameters

Responses

Security

POST /v1/projects/{id}/sources

Parameters

Request body (required)

Responses

Security

GET /v1/projects/{id}/schedules

Parameters

Responses

Security

POST /v1/projects/{id}/runs

Parameters

Request body (required)

Responses

Security

GET /v1/projects/{id}/repository/move

Parameters

Responses

Security

POST /v1/projects/{id}/repository/move

Parameters

Request body (required)

Responses

Security

DELETE /v1/projects/{id}/repository/move

Parameters

Responses

Security

POST /v1/projects/{id}/platform/test

Parameters

Responses

Security

GET /v1/projects/{id}/platform

Parameters

Responses

Security

PUT /v1/projects/{id}/platform

Parameters

Request body (required)

Responses

Security

DELETE /v1/projects/{id}/platform

Parameters

Responses

Security

GET /v1/projects/{id}/members

Parameters

Responses

Security

POST /v1/projects/{id}/members

Parameters

Request body (required)

Responses

Security

GET /v1/projects/{id}/jobs

Parameters

Responses

GET `/v1/table-types`

GET `/v1/projects`

POST `/v1/projects`

GET `/v1/environments`

POST `/v1/projects/{id}/unarchive`

GET `/v1/projects/{id}/sources`

POST `/v1/projects/{id}/sources`

GET `/v1/projects/{id}/schedules`

POST `/v1/projects/{id}/runs`

GET `/v1/projects/{id}/repository/move`

POST `/v1/projects/{id}/repository/move`

DELETE `/v1/projects/{id}/repository/move`

POST `/v1/projects/{id}/platform/test`

GET `/v1/projects/{id}/platform`

PUT `/v1/projects/{id}/platform`

DELETE `/v1/projects/{id}/platform`

GET `/v1/projects/{id}/members`

POST `/v1/projects/{id}/members`

GET `/v1/projects/{id}/jobs`

POST `/v1/projects/{id}/jobs`

GET `/v1/projects/{id}/environments`

POST `/v1/projects/{id}/environments`

POST `/v1/projects/{id}/archive`

PUT `/v1/projects/{id}/agent`

DELETE `/v1/projects/{id}/agent`

GET `/v1/projects/{id}`

PATCH `/v1/projects/{id}`

DELETE `/v1/projects/{id}`

POST `/v1/projects/{id}/sources/{source_id}/test`

GET `/v1/projects/{id}/sources/{source_id}`

PUT `/v1/projects/{id}/sources/{source_id}`

DELETE `/v1/projects/{id}/sources/{source_id}`

PATCH `/v1/projects/{id}/members/{account_id}`

DELETE `/v1/projects/{id}/members/{account_id}`

GET `/v1/projects/{id}/jobs/{job_name}`