API Reference

The Elevating Patterns platform exposes a RESTful HTTP API under the /api/v1/ prefix. Every response is JSON; every request body must be JSON where applicable.

Authentication

When the server is configured with an OIDC provider, every request (except GET /version and OPTIONS) must carry a valid JWT:

Authorization: Bearer <token>

Missing or invalid tokens return 401 Unauthorized. Without auth configuration the server runs in admin mode and accepts all requests without a token.

Addressing Entities

The API offers four equivalent ways to look up a single entity:

Pattern	Resolves by
/api/v1/by-id/<uuid>	Exact entity version UUID -- pins a specific immutable snapshot
/api/v1/by-root/<uuid>	Root UUID -- always resolves to the latest version
/api/v1/by-key/<type_name>/<key>	Type-scoped key -- always resolves to the latest version
/api/v1/by-type/<type_name>/<key>	Alias for by-key

All four prefixes accept the same sub-paths (e.g. /properties, /relationships, /@status).

Key Concepts

• Immutability -- Every update creates a new entity version. The old version remains accessible via its id. The root_id always resolves to the latest version.
• Depth parameter -- Every GET accepts ?depth=<n>. At depth=1 relationships are UUID arrays; at depth>=2 they are expanded to full entity objects recursively.
• Wire format -- Entities are returned as JSON objects with id, root_id, @key, @self, properties, relationships, lists, and traits. The same structure (minus system fields) is used for create and update requests.
• Atomic batch operations -- The POST /api/v1/@upload endpoint creates multiple entities and relationships in a single atomic transaction.

Available Operations

Operation	Method	Example
List all entities of a type	GET	/api/v1/by-type/recipe
Create an entity	POST	/api/v1/by-type/recipe
Read a single entity	GET	/api/v1/by-key/recipe/lasagna
Update an entity	PUT	/api/v1/by-id/<uuid>
Delete an entity	DELETE	/api/v1/by-id/<uuid>?purge=true
Transition lifecycle status	PUT	/api/v1/by-key/recipe/lasagna/@status
Read properties	GET	/api/v1/by-key/recipe/lasagna/properties
Manage relationships	GET / POST / DELETE	/api/v1/by-key/recipe/lasagna/relationships/has_ingredient
Download a BLOB	GET	/api/v1/by-key/recipe/lasagna/properties/photo/@download
Batch upload	POST	/api/v1/@upload
Query by trait	GET	/api/v1/by-trait/is_semantically_tagged

Error Responses

All errors follow a consistent shape:

{ "error": "<human-readable message>" }

Status	Meaning
400	Invalid input, validation failure, or illegal transition
401	Missing or invalid JWT token
404	Entity, type, property, or relationship not found
405	HTTP verb not supported on this route
409	Operation could not be completed (e.g. purge blocked, action failed)
500	Unexpected server-side failure

Further Reading

• Full REST API Reference -- Complete endpoint documentation with request/response examples
• OpenAPI Specification -- Interactive API reference generated from the OpenAPI spec