GT API
Ground Truth (GT) is the editable transcription layer. Reads return the current TSDO JSON for a page; writes replace it (after a successful lock acquisition). Use GT when a human curator is correcting or authoring text; use Pages for read-only multi-format export.
| Method | Path | Summary | Key params | Response |
|---|---|---|---|---|
| POST | /gt/heartbeat/{collection}/{libro}/{page} | Extend the edit lock TTL while a user keeps editing | collection (path:string)libro (path:integer)page (path:integer)body: LockRequest | LockStatusResponse |
| DELETE | /gt/lock/{collection}/{libro}/{page} | Release the edit lock on a page | collection (path:string)libro (path:integer)page (path:integer)body: LockRequest | (no body) |
| GET | /gt/lock/{collection}/{libro}/{page} | Check the current edit lock state for a page | collection (path:string)libro (path:integer)page (path:integer) | LockStatusResponse |
| POST | /gt/lock/{collection}/{libro}/{page} | Acquire (or extend) the edit lock on a page | collection (path:string)libro (path:integer)page (path:integer)body: LockRequest | LockStatusResponse |
| GET | /gt/sessions | List historical edit sessions (audit trail) | — | SessionRow[] |
| GET | /gt/{collection}/{libro}/{page} | Read the TSDO transcription document for a page | collection (path:string)libro (path:integer)page (path:integer) | PageDoc |
| PUT | /gt/{collection}/{libro}/{page} | Write the TSDO transcription document for a page | collection (path:string)libro (path:integer)page (path:integer)body: PageDoc… | (no body) |
| GET | /gt/{collection}/{libro}/{page}/form | Extract printed-form key/value pairs from a page | collection (path:string)libro (path:integer)page (path:integer) | FormData |
Examples
Section titled “Examples”Acquire an edit lock
curl -X POST -H "X-API-Key: $API_KEY" \ "$ARCHAIC/v1/gt/lock/dipucoru/1/0042"Read current GT for a page
curl -H "X-API-Key: $API_KEY" \ "$ARCHAIC/v1/gt/dipucoru/1/0042"Writes and concurrency
Section titled “Writes and concurrency”A PUT to a page must be guarded by an edit lock. Acquire it with
POST /v1/gt/lock/{collection}/{libro}/{page}, check the current state with
a GET on the same path, and release it with a DELETE. While a curator
keeps editing, call POST /v1/gt/heartbeat/{collection}/{libro}/{page} to
extend the lock TTL. A second client trying to acquire a held lock gets a
409, with the holder’s identifier in the response user field.