HTTP API

Asset Core exposes HTTP APIs through two daemons: the write daemon for commits and the read daemon for queries. This separation keeps writes deterministic and reads fast while preserving a single source of truth.

Overview

The API is RESTful with JSON payloads and mandatory bearer-token authentication. Both daemons provide health endpoints for monitoring, and responses include freshness metadata where applicable. This page summarizes the surface area while the OpenAPI reference provides the full contract.

All data endpoints are namespaced under /v1/write/namespaces/{namespace_id} and /v1/read/namespaces/{namespace_id}. Namespaces are the isolation boundary, so include the correct namespace in every request.

The full specification is available in the OpenAPI reference.

Structure

Auth and Namespace Control Plane

These endpoints let operators inspect principals, enumerate permissions, and manage namespace metadata. Use them for governance workflows and for verifying access before sending commits.

Method	Path	Description
GET	/v1/write/auth/whoami	Inspect the current principal
GET	/v1/write/auth/permissions	List permissions for the current token
GET	/v1/write/namespaces	List namespaces
GET	/v1/write/namespaces/{namespace_id}	Fetch namespace details
GET	/v1/write/namespaces/changes	Poll namespace change feed
GET	/v1/write/namespaces/status	List namespace status snapshots
GET	/v1/write/namespaces/{namespace_id}/status	Get namespace status
POST	/v1/write/namespaces/{namespace_id}/lifecycle	Provision or delete a namespace
POST	/v1/write/namespaces/{namespace_id}/operational_state	Set namespace operational mode
POST	/v1/write/namespaces/{namespace_id}/placement	Update placement metadata
POST	/v1/write/namespaces/fork_from_snapshot	Fork a namespace from a snapshot

Namespace-Scoped Write Endpoints

These endpoints handle writes. commit/preflight is non-mutating but uses the same validation rules as a real commit. Always use idempotency keys for production commit workloads so retries remain safe.

Method	Path	Description
POST	/v1/write/namespaces/{namespace_id}/commit	Submit a transaction
POST	/v1/write/namespaces/{namespace_id}/commit/preflight	Validate a transaction without mutation
POST	/v1/write/namespaces/{namespace_id}/commits/{commit_id}/reverse	Apply a stored reverse plan from the undo sidecar (conflict-checked)
POST	/v1/write/namespaces/{namespace_id}/register_class	Register a new asset class
POST	/v1/write/namespaces/{namespace_id}/register_class_shape	Register a shape for a class
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_1d	Register a continuous 1D shape
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_2d	Register a continuous 2D shape

Namespace-Scoped Read Endpoints

Read endpoints expose projections derived from the commit log and include freshness metadata so you can reason about staleness.

Selected read endpoints are listed below; see the OpenAPI reference for the full catalog.

Method	Path	Description
GET	/v1/read/namespaces/{namespace_id}/containers	List containers
GET	/v1/read/namespaces/{namespace_id}/containers/{id}	Get container metadata
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/balances	Get container balances
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/slots	Get container slots
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/cells	Get grid placements
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/free	Find free grid space
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/contents	Unified container contents
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_1d/placements	Continuous 1D placements
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_2d/placements	Continuous 2D placements
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/commits	Container commit history
GET	/v1/read/namespaces/{namespace_id}/commits	Commit history
GET	/v1/read/namespaces/{namespace_id}/classes	List registered classes
GET	/v1/read/namespaces/{namespace_id}/classes/stats	Class registry statistics
GET	/v1/read/namespaces/{namespace_id}/classes/{id}	Get class details
GET	/v1/read/namespaces/{namespace_id}/classes/{id}/shapes	Get class shapes
GET	/v1/read/namespaces/{namespace_id}/instances	List instances
GET	/v1/read/namespaces/{namespace_id}/instances/{id}	Get instance details
GET	/v1/read/namespaces/{namespace_id}/owners/{id}/summary	Owner summary
GET	/v1/read/namespaces/{namespace_id}/freshness	Get freshness metadata
GET	/v1/read/namespaces/{namespace_id}/replay	Replay commit log events
GET	/v1/read/namespaces/{namespace_id}/stream	Stream commits via SSE

Global Health Endpoints

Health and metrics endpoints are designed for load balancers and monitoring systems. They should be part of your standard deployment checks.

Method	Path	Description
GET	/v1/write/health	Write daemon health status
GET	/v1/read/health	Read daemon health status
GET	/v1/write/livez	Write daemon liveness probe
GET	/v1/read/livez	Read daemon liveness probe
GET	/v1/write/readyz	Write daemon readiness probe
GET	/v1/read/readyz	Read daemon readiness probe
GET	/v1/write/startupz	Write daemon startup probe
GET	/v1/read/startupz	Read daemon startup probe
GET	/v1/write/metrics	Write daemon Prometheus metrics (listener when enabled)
GET	/v1/read/metrics	Read daemon Prometheus metrics (listener when enabled)

Fields

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for the current principal
Content-Type	Yes	Must be application/json for POST requests
x-assetcore-namespace	Conditional	Namespace for read health/probe endpoints when not configured
x-assetcore-min-world-seq	No	Require projection to reach a minimum world sequence
x-correlation-id	No	Client correlation ID for tracing

Response Headers

Header	Description
x-asset-idempotency	hit if response was served from idempotency cache
Content-Type	Always application/json

Common Response Fields

Success responses include:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 42,
  "world_seq_end": 42,
  "event_count": 2,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "echo": { ... }
}

Preflight responses include: status, executed_ops, failed_op_index, op_outcomes, and validated_world_seq. See Preflight and Reverse Commit for semantics.

Query responses include freshness:

{
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "freshness": {
    "namespace": 5001,
    "world_seq": 42,
    "commit_log_world_seq": 45,
    "lag": 3,
    "lag_ms": 125
  }
}

Examples

Submit a Transaction

curl -X POST http://localhost:8080/v1/write/namespaces/5001/commit \
  -H "Authorization: Bearer $ASSETCORE_WRITE_TOKEN" \
  -H "x-correlation-id: doc-example-2026-01-15" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": { "type": "balance" },
          "owner": null,
          "policies": null
        }
      }
    ],
    "idempotency_key": "create-container-2026-01-15"
  }'

Response:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 1,
  "world_seq_end": 1,
  "event_count": 1,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "echo": {
    "idempotency_key": "create-container-2026-01-15"
  },
  "created_entities": {
    "containers": [1001]
  }
}

Query Container Balances

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://localhost:8081/v1/read/namespaces/5001/containers/1001/balances

Response:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "freshness": {
    "namespace": 5001,
    "world_seq": 1,
    "commit_log_world_seq": 1,
    "lag": 0,
    "lag_ms": 0
  }
}

Check Health

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://localhost:8080/v1/write/health

Response:

{
  "status": "healthy",
  "version": "0.1.0",
  "api_version": "0.1.0",
  "build_git_sha": "abc123",
  "uptime_secs": 3600
}

Related references

• Transactions - Request body structure
• Error Model - Status codes and error responses
• Preflight and Reverse Commit - Non-mutating validation and undo semantics
• OpenAPI Specification - Canonical HTTP contract