catalog

Discovered ODCS data contracts for project catalog sources.

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

POST `/v1/catalog/profiles`

Ingest an in-flight profile of one schema object (agent-auth).

The agent-harvest write seam for profiles (ADR-159, Decision 3). The agent posts the profile its in-flight profiler took of one schema object while loading it to staging. The api stores it as an attachment of the source’s contract, linked to the contract version stored at that moment; the org is derived from the agent JWT, never the body. Storing a profile never changes the contract and never creates a contract revision. Answers 404 when the source has no contract, and 409 when the stored contract cannot be parsed, so the version to link the profile to is unknown.

Request body (required)

application/json

Property	Type	Required	Description
`environment`	string	Yes

`exact`	boolean	Yes	True when every row was seen.
True when every row was seen.
`mode`	ProfileMode	Yes

`object_name`	string	Yes	The profiled schema object’s ODCS name (schema[].name).
The profiled schema object’s ODCS name (schema[].name).
`profile`	object	Yes	The profile as the agent’s profiler produced it: row count and per-column statistics, signals, PII evidence and verdicts. Counts and labels only; temporal min/max are the only raw values.
The profile as the agent’s profiler produced it: row count and per-column statistics, signals, PII evidence and verdicts. Counts and labels only; temporal min/max are the only raw values.
`profiled_at`	string	Yes	When the load the profile was taken from landed.
When the load the profile was taken from landed.
`project_id`	string	Yes

`run_id`	[integer null]	No	The run whose load the profile was taken from, if any.
The run whose load the profile was taken from, if any.
`source_slug`	string	Yes

Responses

200 The stored profile, without its body.

application/json

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

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`.

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/catalog/object-advice`

Ingest LLM-advisor object-type recommendations (agent-auth).

The agent-harvest write seam (ADR-092). The agent posts LLM-advisor object-type recommendations for a (project, environment, source); the org is derived from the agent JWT, never the body. Upserts on the natural key (source, object_name). It never sets classification or PII-label state: the stored state is carried over (ClassificationStatus). A recommendation is stored apart from the source’s contract and is not a proposal.

Request body (required)

application/json

Property	Type	Required
`environment`	string	Yes

`model`	string	No

`project_id`	string	Yes

`provider`	string	No

`recommendations`	object[]	Yes

`source_slug`	string	Yes

Responses

200 The number of recommendations ingested.

application/json

Property	Type	Required	Description
`ingested`	integer	Yes	The number of recommendations upserted.
The number of recommendations upserted.

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`.

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/catalog/history-states`

List the recorded built history modes of a source (agent-auth).

The agent’s read of the built history modes the api records: for each object of a source and each target its history is on, the history mode that history was built in (HistoryState). It returns exactly the records of the source that project_id, environment and source_slug name: at most one per object and target, ordered by object_name and then target, and an empty data when there are none. The org is derived from the agent JWT, never the query. The environment must be a project environment whose runs dispatch to the calling agent (setProjectEnvironmentAgent), of the project project_id names; otherwise the api answers 403 (code permission_denied) and lists nothing.

This list is the built mode the run-time refusal compares against (HistoryRebuildConflict). The api is the source of truth for it. The built mode is never read from the history table’s structure. An object and target for which this list holds no record has no built mode yet: 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, so a later read lists it. History loaded before the api recorded built modes cannot be verified. The recorded mode is the one reported in the run with the highest run_id by a finished history task that was not skipped, or by a completed rebuild; within that run, the first report stands (HistoryState).

Parameters

Name	In	Required	Type	Description
`project_id`	query	Yes	string	Control-plane project identifier.
Control-plane project identifier.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	query	Yes	string	Catalog source slug.
Catalog source slug.

Responses

200 The source's recorded built history modes; empty when there are none.

application/json

Property	Type	Required	Description
`data`	HistoryState []	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 Code permission_denied: the environment is not assigned to the calling agent (no project environment of project_id whose runs dispatch to it). Nothing is listed.

application/json

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

List the pending history rebuilds of a source (agent-auth).

The agent’s read of confirmed history rebuilds: a history-mode change on an object whose history already existed on a target, confirmed with rebuild_history (HistoryRebuildConflict). It returns exactly the rebuilds of the source that project_id, environment and source_slug name 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. Each rebuild names one object on one target, so two jobs that load the same object to different targets each get their own. A run reads the list for its source before loading history, and acts on a listed rebuild only as HistoryRebuild says: when it loads that object to the rebuild’s target and resolves the object’s history mode to new_history_mode, it drops the object’s history and dependent bridge on that target, rebuilds them from current staging in new_history_mode, and reports it with completeHistoryRebuild; otherwise it drops nothing and the rebuild stays pending. The org is derived from the agent JWT, never the query. The environment must be a project environment whose runs dispatch to the calling agent (setProjectEnvironmentAgent), of the project project_id names; otherwise the api answers 403 (code permission_denied) and lists nothing.

This list is also what the run-time refusal reads (HistoryRebuildConflict): a run loads an existing history table in a history mode other than the one it was built in (the built mode listHistoryStates lists) only when this list names a pending rebuild of that object on that target to that mode, and otherwise refuses. When listHistoryStates lists no built mode for that object on that target, there is nothing to compare against: the run adopts the history mode it resolves and reports it, and that run is not refused.

Parameters

Name	In	Required	Type	Description
`project_id`	query	Yes	string	Control-plane project identifier.
Control-plane project identifier.
`environment`	query	Yes	string	DTAP environment slug.
DTAP environment slug.
`source_slug`	query	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

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 Code permission_denied: the environment is not assigned to the calling agent (no project environment of project_id whose runs dispatch to it). Nothing is listed.

application/json

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

Ingest a harvested ODCS contract (agent-auth).

The agent-harvest write seam (ADR-063). The agent posts a discovered ODCS contract for a (project, environment, source); the org is derived from the agent JWT, never the body. Upserts on the natural key.

A harvested contract 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 a harvest no longer finds keeps its stored state and gets it back when a later harvest finds it again, and one with no stored state has none. So this write never changes an object’s classification or history mode, and it takes no rebuild_history.

Request body (required)

application/json

Property	Type	Required	Description
`contract_yaml`	string	Yes	The ODCS v3 contract document, verbatim YAML. Classification and PII-label state inline in it is ignored; the stored state is carried over (ingestCatalogContract).
The ODCS v3 contract document, verbatim YAML. Classification and PII-label state inline in it is ignored; the stored state is carried over (ingestCatalogContract).
`description`	string	No

`environment`	string	Yes

`name`	string	No

`plugin`	string	No

`project_id`	string	Yes

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

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`.

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/catalog/classifications`

Propose table classifications and PII labels, or file verified auto-approvals (agent-auth).

The agent-harvest write seam for classifications (ADR-159, Decision 4). The agent files a table classification per schema object and a PII label per property; the api writes them into the source’s contract, with their confidence, and stores the result as a new contract revision. Each is stored as proposed, except a table classification filed with status approved that passes the checks below (a verified auto-approval), which is stored approved unless the history hold below applies.

It is one of the operations that own classification state (ClassificationStatus), and the only one an agent calls.

Auto-approval: a table classification the advisor answered with confidence the agent may file with status approved and proposed_by advisor, and must then name the call that produced it in advisor_call_id. Before it writes anything the api checks every object filed with status approved or naming an advisor_call_id, in this order, and the first check that fails answers for the whole request:

An object with status approved names an advisor_call_id, and the request’s proposed_by is advisor. Otherwise 400 (code invalid_argument).
The call is one of the caller’s organization’s advisor calls. Otherwise 400 (code invalid_argument).
The call’s outcome was answered. Otherwise 400 (code invalid_argument).
The call was about the same project, environment, source and object. Otherwise 400 (code invalid_argument).
The call has no result yet. Otherwise 409 (code conflict), so one advisor answer approves at most one classification.

Whichever check fails, nothing is written. A verified object with status approved is stored approved, with approved_by advisor and its confidence, and sets the call’s result to auto_applied. A verified object with status proposed is stored as a proposal and sets the call’s result to awaiting_approval.

History hold: an object filed with status approved whose history the api knows was built on a target in another history mode (HistoryRebuildConflict) is never auto-applied. The api stores it as proposed instead, counts it in proposed_objects, sets the call’s result to awaiting_approval, and names it in held_for_rebuild; a person approves it with rebuild_history. Where the api knows no built mode, a verified auto-approval is stored approved, and the run that filed it adopts the history mode it resolves: the classified mode when no job override sets one, and the override’s mode when one does (an explicit historyMode, ADR-068). That run loads the history in that mode and is not refused (HistoryRebuildConflict), and the api records the mode its finished, non-skipped history task reports with TaskUpdate.history_mode and target (HistoryState). History loaded before the api recorded built modes cannot be verified.

PII labels carry no status and are always proposed. A proposal never replaces an approved classification or label: those are skipped and reported, as are objects and properties the stored contract does not have. The org is derived from the agent JWT, never the body. Answers 404 when the source has no contract, and 409 when the stored contract cannot be parsed or holds a classification or label that cannot be read; neither is overwritten, since it might be an approval.

Request body (required)

application/json

Property	Type	Required	Description
`environment`	string	Yes

`objects`	ObjectClassificationProposal []	No	Proposed table classifications, one per schema object.
Proposed table classifications, one per schema object.
`pii`	PiiLabelProposal []	No	Proposed PII labels, one per property.
Proposed PII labels, one per property.
`project_id`	string	Yes

`proposed_by`	string	No	What proposed the table classifications, for example “advisor”. Defaults to “agent”. An object with status approved is accepted only when this is “advisor”.
What proposed the table classifications, for example “advisor”. Defaults to “agent”. An object with status approved is accepted only when this is “advisor”.
`source_slug`	string	Yes

Responses

200 What was proposed, what was approved, what was held for a rebuild, and what was skipped.

application/json

Property	Type	Required	Description
`approved_objects`	integer	No	Table classifications written as approved by the advisor. Every api that accepts status approved sends it, 0 included. It is not required, so absence stays distinguishable from 0: an api older than auto-approval omits it and stores every table classification as proposed, whatever status was filed. So when approved_objects is present, an object filed with status approved was stored approved exactly when it is named neither in skipped nor in held_for_rebuild; when it is absent, none was stored approved.
Table classifications written as approved by the advisor. Every api that accepts status approved sends it, 0 included. It is not required, so absence stays distinguishable from 0: an api older than auto-approval omits it and stores every table classification as proposed, whatever status was filed. So when approved_objects is present, an object filed with status approved was stored approved exactly when it is named neither in skipped nor in held_for_rebuild; when it is absent, none was stored approved.
`contract_version`	[string null]	No	The version field of the stored contract, or null when nothing was written.
The version field of the stored contract, or null when nothing was written.
`held_for_rebuild`	HistoryModeChange []	No	Objects filed with status approved that were stored as proposed instead, because their history already exists on a target in another history mode: an auto-approval never drops history. They are counted in proposed_objects and wait for a person, who approves them with rebuild_history. Empty or absent when there are none.
Objects filed with status approved that were stored as proposed instead, because their history already exists on a target in another history mode: an auto-approval never drops history. They are counted in proposed_objects and wait for a person, who approves them with rebuild_history. Empty or absent when there are none.
`proposed_objects`	integer	Yes	Table classifications written as proposed.
Table classifications written as proposed.
`proposed_pii`	integer	Yes	PII labels written as proposed.
PII labels written as proposed.
`skipped`	ClassificationSkip []	Yes	Proposals that were not written, and why.
Proposals that were not written, and why.

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`.

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/catalog/history-rebuilds/{rebuild_id}/complete`

Report a history rebuild done (agent-auth).

The agent reports that a run dropped and rebuilt the object’s history on the rebuild’s target in the new mode. The rebuild moves to completed with that run_id and is no longer listed, so a later run does not drop the history again. Idempotent by run_id: reporting a completed rebuild again with the run_id that completed it answers 200 with the record unchanged, so a retry after a lost response is safe; reporting it with another run_id answers 409 (code conflict) and changes nothing. The org is derived from the agent JWT.

Before it completes a pending rebuild the api verifies the report. The calling agent must be the agent the rebuild’s project environment dispatches to (setProjectEnvironmentAgent); otherwise it answers 403 (code permission_denied) and changes nothing. The run must be one of the organization’s runs, of the rebuild’s project, environment and source, executed by the calling agent (Run.agent_id); it must have started after the rebuild was requested (Run.started_at later than requested_at); and it must have loaded the rebuild’s target (its job’s target, or the environment’s platform when the job names none, is the rebuild’s target). A run that fails any of these checks answers 409 (code conflict) and changes nothing, as does a report of a canceled rebuild.

Parameters

Name	In	Required	Type	Description
`rebuild_id`	path	Yes	string	The history rebuild’s id.
The history rebuild’s id.

Request body (required)

application/json

Property	Type	Required	Description
`run_id`	integer	Yes	The run that dropped and rebuilt the object’s history.
The run that dropped and rebuilt the object’s history.

Responses

200 The completed rebuild: moved to completed by this report, or already completed by the same run_id, in which case it is returned unchanged.

application/json

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).

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 Code permission_denied: the calling agent is not the agent the rebuild's project environment dispatches to. Nothing is changed.

application/json

Property	Type	Required	Description
`code`	string	Yes	Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: `invalid_argument`.
`field`	string	No	Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: `slug`.
`message`	string	Yes	Human-readable description of 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 rebuild was already completed by another run_id, it was canceled, or the run is not one of the organization's runs of the rebuild's project, environment and source, executed by the calling agent, started after the rebuild was requested, that loaded its target. Nothing is changed.

application/json

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

Ingest Catalog Profile Request

type: IngestCatalogProfileRequest

Property	Type	Required	Description
`environment`	string	Yes

`exact`	boolean	Yes	True when every row was seen.
True when every row was seen.
`mode`	ProfileMode	Yes

`object_name`	string	Yes	The profiled schema object’s ODCS name (schema[].name).
The profiled schema object’s ODCS name (schema[].name).
`profile`	object	Yes	The profile as the agent’s profiler produced it: row count and per-column statistics, signals, PII evidence and verdicts. Counts and labels only; temporal min/max are the only raw values.
The profile as the agent’s profiler produced it: row count and per-column statistics, signals, PII evidence and verdicts. Counts and labels only; temporal min/max are the only raw values.
`profiled_at`	string	Yes	When the load the profile was taken from landed.
When the load the profile was taken from landed.
`project_id`	string	Yes

`run_id`	[integer null]	No	The run whose load the profile was taken from, if any.
The run whose load the profile was taken from, if any.
`source_slug`	string	Yes

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

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`.

Ingest Object Advice Request

type: IngestObjectAdviceRequest

Property	Type	Required
`environment`	string	Yes

`model`	string	No

`project_id`	string	Yes

`provider`	string	No

`recommendations`	object[]	Yes

`source_slug`	string	Yes

Ingest Object Advice Result

type: IngestObjectAdviceResult

Property	Type	Required	Description
`ingested`	integer	Yes	The number of recommendations upserted.
The number of recommendations upserted.

History State List

type: HistoryStateList

The recorded built history modes of one catalog source, at most one per object and target, ordered by object_name and then target.

Property	Type	Required	Description
`data`	HistoryState []	Yes

History State

type: HistoryState

The history mode one object’s history on one target was built in, as the api records it: the built mode the run-time refusal and the api’s history-mode guard compare against (HistoryRebuildConflict). The api records it from the history_mode and target an agent reports with a history task (TaskUpdate), and from a completed rebuild (completeHistoryRebuild), which records the rebuild’s new_history_mode. The api records the history_mode of a history task only when the task finished (error_code 0 or absent) and was not skipped (neither skip_reason nor waiting set), never that of a failed task (non-zero error_code) or of a skipped one, a refused one (waiting awaiting_rebuild_confirmation) included. A report replaces the record only when its run_id is higher than built_run_id; a report from a run whose run_id is lower than or equal to built_run_id does not replace it, so when concurrent first runs each adopt a mode and their history tasks finish, not skipped, the report of the run with the higher run_id wins. No record: the api knows no built mode for the object on that target (listHistoryStates).

Property	Type	Required	Description
`built_run_id`	integer	Yes	The run with the highest run_id whose finished, non-skipped history task, or completed rebuild, reported history_mode (HistoryState).
The run with the highest run_id whose finished, non-skipped history task, or completed rebuild, reported history_mode (HistoryState).
`history_mode`	string	Yes	The history mode the history on the target was built in. Examples: `scd2`.
The history mode the history on the target was built in. 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 history is on: the job’s target, or the environment’s platform when the job names none (Job.target).
The target platform slug the history is on: the job’s target, or the environment’s platform when the job names none (Job.target).
`updated_at`	string	Yes	When the record was last written.
When the record was last written.

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.

Ingest Catalog Contract Request

type: IngestCatalogContractRequest

Property	Type	Required	Description
`contract_yaml`	string	Yes	The ODCS v3 contract document, verbatim YAML. Classification and PII-label state inline in it is ignored; the stored state is carried over (ingestCatalogContract).
The ODCS v3 contract document, verbatim YAML. Classification and PII-label state inline in it is ignored; the stored state is carried over (ingestCatalogContract).
`description`	string	No

`environment`	string	Yes

`name`	string	No

`plugin`	string	No

`project_id`	string	Yes

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

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`.

Ingest Catalog Classifications Request

type: IngestCatalogClassificationsRequest

Property	Type	Required	Description
`environment`	string	Yes

`objects`	ObjectClassificationProposal []	No	Proposed table classifications, one per schema object.
Proposed table classifications, one per schema object.
`pii`	PiiLabelProposal []	No	Proposed PII labels, one per property.
Proposed PII labels, one per property.
`project_id`	string	Yes

`proposed_by`	string	No	What proposed the table classifications, for example “advisor”. Defaults to “agent”. An object with status approved is accepted only when this is “advisor”.
What proposed the table classifications, for example “advisor”. Defaults to “agent”. An object with status approved is accepted only when this is “advisor”.
`source_slug`	string	Yes

Object Classification Proposal

type: ObjectClassificationProposal

Property	Type	Required	Description
`advisor_call_id`	string	No	The advisor call that produced this classification (Advice.call_id). Required with status approved: the api verifies the call before it writes anything (see ingestCatalogClassifications) and answers 400 when it is absent. Optional with status proposed, and verified the same way when named. The api sets that call’s result: auto_applied for a classification stored approved, awaiting_approval for one stored proposed.
The advisor call that produced this classification (Advice.call_id). Required with status approved: the api verifies the call before it writes anything (see ingestCatalogClassifications) and answers 400 when it is absent. Optional with status proposed, and verified the same way when named. The api sets that call’s result: auto_applied for a classification stored approved, awaiting_approval for one stored proposed.
`business_key`	string[]	No

`confidence`	number	Yes

`history_mode`	string	No	A history mode from listTableTypes.
A history mode from listTableTypes.
`object_name`	string	Yes

`status`	ClassificationStatus	No

`table_type`	string	Yes	A table type from listTableTypes.
A table type from listTableTypes.
`transactional`	boolean	No

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 Proposal

type: PiiLabelProposal

A proposed PII label. It carries no status: a PII label is always stored as proposed and only a person approves it.

Property	Type	Required	Description
`confidence`	number	Yes

`label`	string	Yes	The PII type, for example email, iban, bsn or person_name.
The PII type, for example email, iban, bsn or person_name.
`method`	string	Yes	The evidence the label rests on: validators, name_dictionary, or both joined by “+”.
The evidence the label rests on: validators, name_dictionary, or both joined by “+”.
`object_name`	string	Yes

`property_name`	string	Yes

Ingest Catalog Classifications Result

type: IngestCatalogClassificationsResult

Property	Type	Required	Description
`approved_objects`	integer	No	Table classifications written as approved by the advisor. Every api that accepts status approved sends it, 0 included. It is not required, so absence stays distinguishable from 0: an api older than auto-approval omits it and stores every table classification as proposed, whatever status was filed. So when approved_objects is present, an object filed with status approved was stored approved exactly when it is named neither in skipped nor in held_for_rebuild; when it is absent, none was stored approved.
Table classifications written as approved by the advisor. Every api that accepts status approved sends it, 0 included. It is not required, so absence stays distinguishable from 0: an api older than auto-approval omits it and stores every table classification as proposed, whatever status was filed. So when approved_objects is present, an object filed with status approved was stored approved exactly when it is named neither in skipped nor in held_for_rebuild; when it is absent, none was stored approved.
`contract_version`	[string null]	No	The version field of the stored contract, or null when nothing was written.
The version field of the stored contract, or null when nothing was written.
`held_for_rebuild`	HistoryModeChange []	No	Objects filed with status approved that were stored as proposed instead, because their history already exists on a target in another history mode: an auto-approval never drops history. They are counted in proposed_objects and wait for a person, who approves them with rebuild_history. Empty or absent when there are none.
Objects filed with status approved that were stored as proposed instead, because their history already exists on a target in another history mode: an auto-approval never drops history. They are counted in proposed_objects and wait for a person, who approves them with rebuild_history. Empty or absent when there are none.
`proposed_objects`	integer	Yes	Table classifications written as proposed.
Table classifications written as proposed.
`proposed_pii`	integer	Yes	PII labels written as proposed.
PII labels written as proposed.
`skipped`	ClassificationSkip []	Yes	Proposals that were not written, and why.
Proposals that were not written, and why.

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.

Classification Skip

type: ClassificationSkip

Property	Type	Required	Description
`object_name`	string	Yes

`property_name`	string	No	Set for a PII label; absent for a table classification.
Set for a PII label; absent for a table classification.
`reason`	string	Yes	approved (an approved classification is never replaced), or not_found (the stored contract has no such object or property). Valid values are: `approved`, `not_found`.
approved (an approved classification is never replaced), or not_found (the stored contract has no such object or property). Valid values are: `approved`, `not_found`.

History Rebuild Completion

type: HistoryRebuildCompletion

The payload with which an agent reports a history rebuild done.

Property	Type	Required	Description
`run_id`	integer	Yes	The run that dropped and rebuilt the object’s history.
The run that dropped and rebuilt the object’s history.

Last updated on October 31, 2026

Docs

catalog

POST /v1/catalog/profiles

Request body (required)

Responses

Security

POST /v1/catalog/object-advice

Request body (required)

Responses

Security

GET /v1/catalog/history-states

Parameters

Responses

Security

GET /v1/catalog/history-rebuilds

Parameters

Responses

Security

POST /v1/catalog/contracts

Request body (required)

Responses

Security

POST /v1/catalog/classifications

Request body (required)

Responses

Security

POST /v1/catalog/history-rebuilds/{rebuild_id}/complete

Parameters

Request body (required)

Responses

Security

Schemas

Ingest Catalog Profile Request

Profile Mode

Catalog Profile Summary

Error

Ingest Object Advice Request

Ingest Object Advice Result

History State List

History State

History Rebuild List

History Rebuild

History Rebuild Requester Type

History Rebuild Status

Ingest Catalog Contract Request

Catalog Source

Ingest Catalog Classifications Request

Object Classification Proposal

Classification Status

Pii Label Proposal

Ingest Catalog Classifications Result

History Mode Change

Classification Skip

History Rebuild Completion

On this page

POST `/v1/catalog/profiles`

POST `/v1/catalog/object-advice`

GET `/v1/catalog/history-states`

GET `/v1/catalog/history-rebuilds`

POST `/v1/catalog/contracts`

POST `/v1/catalog/classifications`

POST `/v1/catalog/history-rebuilds/{rebuild_id}/complete`