Endpoints
Complete HTTP endpoint catalog of alexandria-server (/v1 and /pub) and of the alexandria-client admin API under specification v0.3.0.
Endpoints
In the tables below, Who is one of: public, admin, steward (of the namespace in the path) or steward or admin. See authentication for the rules.
1. alexandria-server — /v1
Responses are compact JSON-LD (application/ld+json). Lists are @graph documents. Errors are application/problem+json with a catalog code.
Namespaces and stewards
| Method | Path | Who | Result |
|---|---|---|---|
POST | /v1/namespaces | admin | 201 with Location. Body: slug, optional title, description. |
GET | /v1/namespaces | public | All namespaces. |
GET | /v1/namespaces/{ns} | public | One namespace. |
GET | /v1/namespaces/{ns}/stewards | steward or admin | Stewards of the namespace. |
POST | /v1/namespaces/{ns}/stewards | admin | 201. Body: iss, sub, optional label. |
DELETE | /v1/namespaces/{ns}/stewards/{id} | admin | 204. |
Vocabularies
| Method | Path | Who | Result |
|---|---|---|---|
POST | /v1/namespaces/{ns}/vocabularies | steward | 201. Body: name, kind (hosted or proxy), media_type, upstream for proxies, optional title, description. |
GET | /v1/namespaces/{ns}/vocabularies | public | Vocabularies with their revisions. |
GET | /v1/namespaces/{ns}/vocabularies/{name} | public | One vocabulary. |
PUT | /v1/namespaces/{ns}/vocabularies/{name}/content | steward | 201 for a new revision, 200 when the bytes are unchanged. ETag is the digest. Optional If-Match. |
POST | /v1/namespaces/{ns}/vocabularies/{name}:refresh | steward | Re-fetch a proxy upstream: 201 for a new revision, 200 when unchanged. |
Drafts and candidates
| Method | Path | Who | Result |
|---|---|---|---|
POST | /v1/namespaces/{ns}/drafts | steward | 201 with Location and ETag. |
GET | /v1/namespaces/{ns}/drafts/{id} | steward | The draft and its ETag. |
PUT | /v1/namespaces/{ns}/drafts/{id} | steward | Replace. Requires If-Match (428, 412). |
POST | /v1/namespaces/{ns}/drafts/{id}:validate | steward | Report: valid, class, findings[]. No effect. |
POST | /v1/namespaces/{ns}/drafts/{id}:propose | steward | 201 with the frozen candidate. |
GET | /v1/namespaces/{ns}/candidates/{id} | steward | State, version, class, diff, planned record and lifecycle. |
POST | /v1/namespaces/{ns}/candidates/{id}:approve | steward | 201 with the signed VersionRecord. Optional body grace_window. |
POST | /v1/namespaces/{ns}/candidates/{id}:reject | steward | The rejected candidate. Optional body comment. |
Versions
| Method | Path | Who | Result |
|---|---|---|---|
GET | /v1/namespaces/{ns}/versions | public | The signed VersionListing. Cache-Control: no-cache. 404 until the first release. |
GET | /v1/namespaces/{ns}/versions/{version} | public | The signed VersionRecord. |
POST | /v1/namespaces/{ns}/versions/{version}:revoke | steward | The re-signed record. Body: justification, optional revoked_from. |
Events
| Method | Path | Who | Result |
|---|---|---|---|
GET | /v1/events | admin | Hub-wide event log. |
GET | /v1/namespaces/{ns}/events | steward | Events of the namespace. |
Both accept after (an event id or IRI) and limit (default 100, maximum 500).
There are no list endpoints for drafts or candidates. Their ids appear in the namespace events (draft.created, candidate.proposed), which is how the console builds its index.
2. alexandria-server — /pub
All routes are GET, public and unauthenticated.
| Path | Result |
|---|---|
/pub/{ns} | 303 to the head of the namespace. |
/pub/{ns}/{version}/{path} | A file of a published package. |
/pub/{ns}/vocab/{name} | 303 to the latest revision. |
/pub/{ns}/vocab/{name}/r/{n} | A vocabulary revision. |
/pub/packages/{digest}/manifest.json | A signed PackageManifest. |
/pub/blobs/sha256/{hex} | A blob by its SHA-256. |
/pub/_vhub/v1/context.jsonld | The JSON-LD context of Appendix A.5. |
/pub/_vhub/v1/vocab.ttl | The vocabulary of the context terms. |
Redirects carry Cache-Control: no-cache. Every other route is immutable: Cache-Control: public, max-age=31536000, immutable and an ETag equal to the SHA-256 of the body.
When the binary is built with the gui tag, /ui/ serves the console.
3. alexandria-client — Admin Listener
Unauthenticated, bound to its own listener. JSON responses; errors are application/problem+json.
| Method | Path | Result |
|---|---|---|
GET | /status | State, versions and roles, last accepted listing, hub DID, rules revision, clock skew. |
GET | /versions | Lifecycle records with state and whether the package is held. |
GET | /rules | Rule set; ETag is the revision. |
PUT | /rules | Replace the rule set. Requires If-Match. |
POST | /rules | Add a rule. Requires If-Match. 201. |
GET | /rules/{id} | One rule. |
PUT | /rules/{id} | Replace one rule. Requires If-Match. |
DELETE | /rules/{id} | Delete one rule. Requires If-Match. 204. |
POST | /rules:explain | Decision for a described request, without effects. |
GET | /agreements/{id} | A captured agreement with usable. |
GET | /audit/reports/latest | Latest passive audit report, or 404. |
GET | /healthz | 200 while the process is alive. |
GET | /readyz | 200 in Active, Transition or Degraded; 503 otherwise. |
GET | /metrics | OpenMetrics exposition. |
4. Problem Documents
{
"@context": "https://127.0.0.1:8443/pub/_vhub/v1/context.jsonld",
"type": "https://w3id.org/alexandria-vhub/problems#API_FORBIDDEN_ROLE",
"title": "API_FORBIDDEN_ROLE",
"status": 403,
"detail": "the principal has no permission for this operation",
"code": "API_FORBIDDEN_ROLE",
"severity": "error"
}| Status | Typical codes |
|---|---|
400 | Unreadable request body (no catalog code). |
401 | API_UNAUTHENTICATED |
403 | API_FORBIDDEN_ROLE |
404 | API_NOT_FOUND |
409 | API_INVALID_STATE, NS_EXISTS, STEWARD_EXISTS, VOCAB_EXISTS |
412 | API_PRECONDITION_FAILED |
413 | VOCAB_TOO_LARGE |
422 | NS_*, VOCAB_*, DATES_*, LIFECYCLE_*, compiler findings, RULES_* |
428 | API_PRECONDITION_REQUIRED |
502 | VOCAB_UPSTREAM_FAILED |
503 | RELEASE_ABORTED, SIGNER_KEY_NOT_PUBLISHED |
A validation failure with several findings returns one problem whose findings[] holds one entry per finding.
The repository ships Postman collections for both binaries in postman/.
API & Development
HTTP surfaces of alexandria-server and alexandria-client, authentication, observability, the conformance suite and the development workflow.
Authentication & Authorization
How alexandria-server authenticates OAuth 2.0 access tokens (A1–A5), authorizes operations with the admin role and namespace stewards, and how the laboratory identity provider works.