Cross-product references

The one door a reference crosses a product boundary through: making a project on a surface that has none of its own, and resolving a stored id into the words to draw beside it. What crosses is an identity, never content — a title is resolved where it is drawn, and a reference nobody may see resolves to nothing rather than to an error. Both products have to be active on the workspace.

2 operations. Every path is relative to the instance origin; every response body is JSON unless stated. The endpoint descriptions below come straight from the server’s own route table. See API for authentication, errors and pagination.

POST /api/v1/workspaces/{workspaceId}/cross-refs/resolve

Resolve stored reference ids into the words to draw beside them — what a reference across a product boundary points at (ADR-0036). What crosses is an IDENTITY: no title is stored on the other side, so it is resolved where it is drawn, and the answer says which product each id was found in. Requires BOTH products active on the workspace (ADR-0033 D1) and read on the block; an id that fails either — or is unknown or trashed — is absent from the answer rather than an error, because a 404 per id would say which ids exist.

resolveCrossRefs · token scope: session only

Path parameters

• workspaceId · string (uuid) — required

Request body — application/json, required

• ids · string (uuid)[] — required, 1–50 items

Response 200 — application/json

• items · object[] — required
  • id · string (uuid) — required
  • product · "basalt" | "lithic" | "tecto" — required
  • title · string — required
  • icon · string | null — required
  • url · string — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/cross-refs/projects

Make a project in the other product, or name one that already exists (name creates, projectId links). Only for a surface that has no projects of its own — the product that has them writes them itself, through its own document. A created project lands in that product’s projects document, which this route makes when there is none: the caller names no document, because it may not show the other product’s (ADR-0025 D1). Requires BOTH products active and edit on the collection. The one route in the API that MAKES content for a product other than the asking one; ADR-0036 is where that is argued.

createProjectRef · token scope: session only

Path parameters

• workspaceId · string (uuid) — required

Request body — application/json, required

• collectionId · string (uuid) — required
• name · string — length 1–500
• projectId · string (uuid)

Response 200 — application/json

• id · string (uuid) — required
• product · "basalt" | "lithic" | "tecto" — required
• title · string — required
• icon · string | null — required
• url · string — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64