Publication Requests API

Publication Requests API

For the owner-facing explanation of private previews, public URLs, branches, and recovery, see Publishing People and Public Family Branches.

The publication API has one public workflow: create a request, wait for its private preview, and submit one owner-confirmed Publish command. Verification, approval records, promotion planning, preflight, artifact writes, and anonymous public-result checks are automatic internal stages.

Automation tokens with tree:publication:update may create and inspect requests or retry safe stored work. Publishing and discarding require an interactive owner session. A token can prepare work but cannot authorize public disclosure.

Minimal sequence

1. POST /api/trees/:treeId/publication/requests with explicit TreePerson ids.
2. Poll the returned request or operation until the request is ready_to_review.
3. Show the private preview links and branch ids to the owner.
4. POST /api/trees/:treeId/publication/requests/:requestId/publish with the exact preview revision, selected branch ids, and an idempotency key.
5. Poll until published or needs_attention.

The publish intent is immutable. Reusing its idempotency key with a different revision or branch selection returns a conflict. Retry resumes only the stored stage and cannot broaden the selection. Refresh creates a new private preview and therefore requires a new Publish confirmation.

Owner-visible request states

preparing_preview, ready_to_review, publishing, published, needs_attention, and discarded are the complete owner-visible state set. Machine stage details appear only as bounded progress and safe issues.

Endpoint contracts

POST /api/trees/:treeId/publication/requests

Create an owner-only publication preview request.

Responses:

Request example:

{
  "treePersonIds": [
    "tp-a",
    "tp-b"
  ],
  "language": "ru",
  "note": "Maternal branch"
}

Notes:

• Creation never makes data public.
• Preview generation continues without an open browser tab.

GET /api/trees/:treeId/publication/requests

List compact active publication requests or history.

Responses:

Query example:

{
  "view": "active",
  "limit": 25
}

Notes:

• List responses exclude snapshots, graph geometry, digests, and machine-check arrays.

GET /api/trees/:treeId/publication/requests/:requestId

Read one private publication request and its family branches.

Responses:

Notes:

• Automation-token responses set canPublish to false.

POST /api/trees/:treeId/publication/requests/:requestId/publish

Publish the exact family branches confirmed by the owner.

Responses:

Request example:

{
  "previewRevisionId": "revision-1",
  "branchIds": [
    "branch-a"
  ],
  "idempotencyKey": "publish-request-1-revision-1"
}

Notes:

• Verification, approvals, preflight, execution, and public-result checks run automatically.

POST /api/trees/:treeId/publication/requests/:requestId/refresh

Prepare a new immutable private preview for the same selection.

Responses:

Request example:

{}

Notes:

• A changed preview always requires a new owner Publish confirmation.

POST /api/trees/:treeId/publication/requests/:requestId/retry

Retry only the stored retryable stage.

Responses:

Request example:

{}

Notes:

• Retry cannot change revision, branches, identities, or digests.

POST /api/trees/:treeId/publication/requests/:requestId/discard

Discard an unpublished private preview request.

Responses:

Request example:

{}

Notes:

• Discard never unpublishes an already completed public result.

GET /api/trees/:treeId/publication/operations/:operationId

Read safe automatic publication progress.

Responses:

Notes:

• Responses never expose leases, storage keys, receipts, or execution cursors.

GET /api/trees/:treeId/publication/candidates

Discover bounded age-eligible publication candidates.

Responses:

Query example:

{
  "q": "Иван",
  "limit": 25
}

Notes:

• Candidate discovery never authorizes publication.