read Endpoints

Read daemon operations (queries and projections)

Endpoints

GET /v1/read/health

Summary: OpenAPI metadata for the read daemon health check endpoint.

Operation ID: read_health_endpoint

Parameters

Name	In	Required	Type	Description
x-assetcore-namespace	header	yes	NamespaceId	Namespace scope for read health probes (required).

Responses

Status	Description	Schema
200	Read daemon health status	ReadHealthResponse
401	Unauthorized request	ProblemDetails
403	Forbidden request	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Service unavailable	ProblemDetails

GET /v1/read/livez

Summary: OpenAPI metadata for the read daemon liveness probe.

Operation ID: read_livez_endpoint

Parameters

Name	In	Required	Type	Description
x-assetcore-namespace	header	yes	NamespaceId	Namespace scope for read health probes (required).

Responses

Status	Description	Schema
200	Read daemon liveness probe	ProbeResponse
401	Unauthorized request	ProblemDetails
403	Forbidden request	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Service unavailable	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/classes

Summary: OpenAPI metadata for the class registry listing endpoint.

Operation ID: class_list_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
cursor	query	no	string	Optional cursor anchored to the last seen class identifier.
limit	query	no	integer	Maximum number of entries to return (defaults to 20, capped at 200).

Responses

Status	Description	Schema
200	Paginated class registry listing	ClassListResponse
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/classes/{id}

Summary: OpenAPI metadata for the class detail endpoint.

Operation ID: class_detail_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Class external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Class detail	ClassDetailResponse
400	Invalid class identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Class not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/classes/{id}/shapes

Summary: OpenAPI metadata for the class shapes endpoint.

Operation ID: class_shapes_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Class external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Class shape enumeration	ClassShapesResponse
400	Invalid class identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Class not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/classes/stats

Summary: OpenAPI metadata for the class statistics endpoint.

Operation ID: class_stats_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Class registry and store statistics	ClassStatsResponse
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/commits

Summary: OpenAPI metadata for the commit history endpoint.

Operation ID: commits_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
limit	query	no	integer	Maximum number of commits to return (capped at 100).
from_world_seq	query	no	integer	Starting world sequence to return (default: 0, start from beginning).

Responses

Status	Description	Schema
200	Commit history	CommitsResponse
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers

Summary: OpenAPI metadata for the container listing endpoint.

Operation ID: container_list_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
owner	query	no	string	Optional owner filter (external owner identifier).
kind	query	no	string	Optional kind filter (balance, grid, slots, continuous_line_1d, continuous_grid_2d).
cursor	query	no	string	Optional cursor anchored to the last seen container identifier.
limit	query	no	integer	Maximum number of entries to return (clamped to [MAX_LIST_LIMIT]).

Responses

Status	Description	Schema
200	Container listing	ContainerListResponse
400	Invalid filter parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}

Summary: OpenAPI metadata for the container detail lookup endpoint.

Operation ID: container_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Container detail snapshot	ContainerResponse
400	Invalid container identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/balances

Summary: OpenAPI metadata for the container balance listing endpoint.

Operation ID: container_balances_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
class	query	no	string	Optional filter on the asset class external identifier (e.g., "class-1"). When present, only balances matching this class are included in the response.
key	query	no	string	Optional filter on the variant key ([StackKey]) expressed as a string (e.g., "42"). When present, only balances with this variant key are included. If the system does not use variant keys for a class, omit this.

Responses

Status	Description	Schema
200	Container balances	BalanceResponse
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/commits

Summary: OpenAPI metadata for the container commit history endpoint.

Operation ID: container_commits_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
limit	query	no	integer	Maximum number of commits to return (capped at 100).
from_world_seq	query	no	integer	Starting world sequence to return (default: 0, start from beginning).

Responses

Status	Description	Schema
200	Container commit history	CommitsResponse
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/contents

Summary: OpenAPI metadata for the container contents endpoint.

Operation ID: container_contents_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Container contents	ContainerContentsResponse
400	Invalid container identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/continuous_1d/placements

Summary: OpenAPI metadata for the continuous 1D placement endpoint.

Operation ID: container_continuous_placements_1d_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
min_x	query	no	integer	Optional inclusive minimum X bound (fixed-point units).
max_x	query	no	integer	Optional inclusive maximum X bound (fixed-point units).

Responses

Status	Description	Schema
200	Continuous 1D container placements	Continuous1dPlacementsResponse
400	Invalid continuous 1D region parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/continuous_2d/placements

Summary: OpenAPI metadata for the continuous 2D placement endpoint.

Operation ID: container_continuous_placements_2d_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
min_x	query	no	integer	Optional inclusive minimum X bound (fixed-point units).
min_y	query	no	integer	Optional inclusive minimum Y bound (fixed-point units).
max_x	query	no	integer	Optional inclusive maximum X bound (fixed-point units).
max_y	query	no	integer	Optional inclusive maximum Y bound (fixed-point units).

Responses

Status	Description	Schema
200	Continuous 2D container placements	Continuous2dPlacementsResponse
400	Invalid continuous 2D region parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/grid/cells

Summary: OpenAPI metadata for the grid placement endpoint.

Operation ID: container_grid_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
x	query	no	integer	0-based X coordinate (column).
y	query	no	integer	0-based Y coordinate (row).
width	query	no	integer	Region width (cells).
height	query	no	integer	Region height (cells).

Responses

Status	Description	Schema
200	Container grid placements	GridPlacementResponse
400	Invalid grid region parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/grid/free

Summary: OpenAPI metadata for the grid free-region search endpoint.

Operation ID: container_grid_free_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
width	query	no	integer	Desired shape width (cells).
height	query	no	integer	Desired shape height (cells).

Responses

Status	Description	Schema
200	Grid free-region search	GridFreeResponse
400	Invalid grid shape parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/containers/{id}/slots

Summary: OpenAPI metadata for the slot occupancy endpoint.

Operation ID: container_slots_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Container external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Slot container occupancy	SlotResponse
400	Invalid container identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Container not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/freshness

Summary: OpenAPI metadata for the projection freshness endpoint.

Operation ID: freshness_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Projection freshness metadata	FreshnessResponse
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Projection unavailable	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/instances

Summary: OpenAPI metadata for the instance listing endpoint.

Operation ID: instance_list_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
class	query	no	string	Optional class filter (external identifier).
variant_key	query	no	string	Optional variant key filter.
owner	query	no	string	Optional owner filter (external owner identifier).
cursor	query	no	string	Optional cursor anchored to the last seen instance identifier.
limit	query	no	integer	Maximum number of entries to return (clamped to [MAX_LIST_LIMIT]).

Responses

Status	Description	Schema
200	Instance listing	InstanceListResponse
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/instances/{id}

Summary: OpenAPI metadata for the instance detail endpoint.

Operation ID: instance_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Instance external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Instance detail	InstanceResponse
400	Invalid instance identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Instance not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/owners/{id}/summary

Summary: OpenAPI metadata for the owner summary endpoint.

Operation ID: owner_summary_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
id	path	yes	ExternalId	Owner external identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.

Responses

Status	Description	Schema
200	Owner summary	OwnerSummaryResponse
400	Invalid owner identifier	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Owner not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/replay

Summary: OpenAPI metadata for the replay endpoint.

Operation ID: replay_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
from_world_seq	query	no	integer	World sequence to replay from (inclusive).
limit	query	no	integer	Maximum number of batches to return (capped at 100).

Responses

Status	Description	Schema
200	Replay batches	ReplayResponse
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails

GET /v1/read/namespaces/{namespace_id}/stream

Summary: OpenAPI metadata for the read stream endpoint.

Operation ID: read_stream_endpoint

Parameters

Name	In	Required	Type	Description
namespace_id	path	yes	NamespaceId	Namespace identifier
x-assetcore-min-world-seq	header	no	integer	Require projection to reach the specified world sequence before responding.
Last-Event-Id	header	no	integer	SSE resume cursor; stream resumes at last_event_id + 1.
from_world_seq	query	no	integer	Optional world sequence to begin streaming from (inclusive).
limit	query	no	integer	Optional maximum number of batches to emit before closing the stream.

Responses

Status	Description	Schema
200	Stream of commit batches (SSE)	StreamEntry
400	Invalid query parameters	ProblemDetails
401	Unauthorized request	ProblemDetails
404	Namespace not found	ProblemDetails
425	Projection has not reached the requested world sequence	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Internal server error	ProblemDetails
503	Stream unavailable	ProblemDetails

GET /v1/read/readyz

Summary: OpenAPI metadata for the read daemon readiness probe.

Operation ID: read_readyz_endpoint

Parameters

Name	In	Required	Type	Description
x-assetcore-namespace	header	yes	NamespaceId	Namespace scope for read health probes (required).

Responses

Status	Description	Schema
200	Read daemon readiness probe	ReadReadyzResponse
401	Unauthorized request	ProblemDetails
403	Forbidden request	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Service unavailable	ProblemDetails
503	Reader not ready	ReadReadyzResponse

GET /v1/read/startupz

Summary: OpenAPI metadata for the read daemon startup probe.

Operation ID: read_startupz_endpoint

Parameters

Name	In	Required	Type	Description
x-assetcore-namespace	header	yes	NamespaceId	Namespace scope for read health probes (required).

Responses

Status	Description	Schema
200	Read daemon startup probe	ProbeResponse
401	Unauthorized request	ProblemDetails
403	Forbidden request	ProblemDetails
429	Quota exceeded	ProblemDetails
500	Service unavailable	ProblemDetails