InkSmith Press exposes a versioned HTTP API for shared templates and production render jobs. Press Control in Desktop uses the same management boundary. The API is for authorised clients; it is not required for local Desktop work.
Discover the instance
A Press deployment exposes GET /health, GET /ready, and GET /api/v1/instance. Use readiness and instance discovery to check the API version, renderer compatibility, and accepted template schema before sending work.
The server should sit behind its configured HTTPS gateway for remote use. Follow the Press deployment guide for Docker and Windows Service options.
Authenticate and scope a client
Send Authorization: Bearer <token> on protected requests. API clients receive only the scopes they need. For rendering, the relevant permissions are renders.create, jobs.read, and outputs.read. Management scopes include templates.read, templates.write, and templates.publish.
Store the issued credential outside templates, source control, and browser JavaScript. Press stores API-client credentials as hashes and supports immediate revocation.
Submit and retrieve a render job
Only an active published template can be rendered. A typical request is:
POST /api/v1/render-jobs
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: invoice-1042
{"template_id":"<published-template-id>","data":{"customer":{"name":"Ada"}}}
The job is asynchronous. Read GET /api/v1/render-jobs/:id until its status is completed, failed, or cancelled. Once complete, GET /api/v1/render-jobs/:id/output returns the PDF if the caller has outputs.read.
Reuse the same idempotency key after an uncertain network failure only for the same request and credential. Reusing it with changed input produces 409 idempotency_conflict.
Manage template revisions
Collections, templates, drafts, versions, and publication are server-owned. Draft content transfers use application/vnd.inksmith.template. Saves and publication require the current opaque revision in If-Match; a stale draft update receives 412 template_revision_conflict. A published version is immutable. Unpublish and rollback operate on the separate publication revision.
See Press Control for the Desktop editing workflow. The Press deployment guide explains the supported hosting paths and current limits.
Current scope: Interactive user and role administration, certificate enrollment, and some retention controls are still under development. Treat the published API and permission checks as the contract; do not bypass them with direct database changes.