{"openapi": "3.1.0", "info": {"title": "Tvarka Proof API", "version": "1.30.0", "x-status": "Live and publicly reachable at https://sign-api.tvarka.pro since 2026-08-27, on both production boxes and behind Cloudflare. The first production tenant was onboarded 2026-08-28 and the launch gate ceremony ran the same day: a production signing ordered through this API was signed with a real eID (Mobile-ID) and validated QUALIFIED_VALID, and webhook delivery was exercised the same day against an external production receiver with the HMAC signature and idempotency key verified on arrival.", "description": "A fact is fixed at a moment in time. A file is sealed with a qualified timestamp. A web page is captured as it looked. Every proof carries a code and a link that anyone can check.", "contact": {"name": "Tvarka", "email": "info@tvarka.pro", "url": "https://tvarka.pro"}}, "servers": [{"url": "https://sign-api.tvarka.pro", "description": "Production and sandbox (selected by the key)"}], "security": [{"bearerAuth": []}, {"apiKeyHeader": []}, {"agentOAuth": ["sign.read", "sign.signings"]}], "tags": [{"name": "Webhooks", "description": "Callback URLs for automation platforms."}, {"name": "Account", "description": "Who the key acts for."}, {"name": "Files", "description": "Reusable uploads retained for seven days."}, {"name": "Timestamps", "description": "Qualified timestamps of documents, hashes and web pages."}, {"name": "Capture collections", "description": "Web pages captured again on a schedule, or up to 20 at once as one case."}], "paths": {"/v1/capture-monitors": {"get": {"tags": ["Capture collections"], "operationId": "listCaptureMonitors", "summary": "List the latest 100 capture monitors", "responses": {"200": {"description": "Monitors belonging to this API client.", "content": {"application/json": {"schema": {"type": "object", "properties": {"monitors": {"type": "array", "items": {"$ref": "#/components/schemas/CaptureMonitor"}}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}, "post": {"tags": ["Capture collections"], "operationId": "createCaptureMonitor", "summary": "Capture a page now and on a bounded recurring schedule", "description": "Reuses timestamp jobs and their completed/failed webhooks. No overlapping\ncaptures or catch-up bursts. Each completed capture uses normal pricing.\nmaxCaptures counts attempts, including failures; pauses and failures do\nnot reset it. Loss of billing or workspace access pauses the monitor.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateCaptureMonitor"}}}}, "responses": {"201": {"description": "Monitor created and first capture queued.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CaptureMonitor"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/capture-monitors/{monitorId}": {"get": {"tags": ["Capture collections"], "operationId": "getCaptureMonitor", "summary": "Read a monitor", "responses": {"200": {"description": "Current schedule and latest timestamp ID.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CaptureMonitor"}}}}, "404": {"description": "Not found for this client."}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}, "parameters": [{"name": "monitorId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}, "patch": {"tags": ["Capture collections"], "operationId": "updateCaptureMonitor", "summary": "Pause or resume a monitor", "description": "Pause leaves an already queued capture running. Resume starts the next interval from now, without catching up. Completed limits cannot be reset.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["status"], "properties": {"status": {"type": "string", "enum": ["active", "paused"]}}}}}}, "responses": {"200": {"description": "Updated monitor.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CaptureMonitor"}}}}, "400": {"description": "Invalid status or exhausted schedule."}, "404": {"description": "Not found for this client."}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}, "parameters": [{"name": "monitorId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/capture-bundles": {"get": {"tags": ["Capture collections"], "operationId": "listCaptureBundles", "summary": "List the latest 100 case bundles", "responses": {"200": {"description": "Bundles belonging to this client.", "content": {"application/json": {"schema": {"type": "object", "properties": {"bundles": {"type": "array", "items": {"$ref": "#/components/schemas/CaptureBundle"}}}}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}, "post": {"tags": ["Capture collections"], "operationId": "createCaptureBundle", "summary": "Queue a URL list as one evidence bundle", "description": "One ordinary capture per distinct URL, in input order. Shared page options\napply to every URL. Completed captures use normal pricing; manifest sealing\nand ZIP assembly have no additional fee. Once all captures settle, the\nscheduled worker seals the manifest with a qualified RFC 3161 timestamp.\nFailed captures remain listed. No crawl or recurring schedule is created.\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateCaptureBundle"}}}}, "responses": {"202": {"description": "Bundle queued.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CaptureBundle"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/capture-bundles/{bundleId}": {"get": {"tags": ["Capture collections"], "operationId": "getCaptureBundle", "summary": "Read a case bundle and its capture outcomes", "responses": {"200": {"description": "Bundle state.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CaptureBundle"}}}}, "404": {"description": "Not found for this client."}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}, "parameters": [{"name": "bundleId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/capture-bundles/{bundleId}/file": {"get": {"tags": ["Capture collections"], "operationId": "downloadCaptureBundle", "summary": "Download the sealed manifest and all evidence files in one ZIP", "responses": {"200": {"description": "ZIP containing manifest.json, its RFC 3161 manifest.tst, and numbered exhibits.", "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}}}, "404": {"description": "Not found for this client."}, "409": {"description": "Captures or manifest sealing are pending."}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}, "parameters": [{"name": "bundleId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/files": {"post": {"tags": ["Files"], "operationId": "uploadFile", "summary": "Store a document once for reuse across signings", "description": "Returns a `fileToken` a later signing may reference instead of\ncarrying base64 again. Multipart accepts one binary part named file,\nup to 100,000,000 bytes; JSON accepts up to 15 MiB decoded. Format\nvalidation is identical for both transports. Office files and\nimages are converted to PDF/A-2b on upload (v1.9.0), so the stored\nfile and its `name` are the PDF.\n\nThe bytes are **copied** into each signing that uses the token, never\nshared by reference: deleting a file, or letting it expire, can never\nreach backwards into a signing that already used it.\n", "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "required": ["file"], "additionalProperties": false, "properties": {"file": {"type": "string", "format": "binary", "description": "One document, at most 100,000,000 bytes. Preserve its filename extension."}}}}, "application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}}, "required": ["name", "content"], "additionalProperties": false}}}}, "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "201": {"description": "The stored file.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredFile"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}}}}, "/v1/conversions": {"post": {"tags": ["Files"], "operationId": "convertDocument", "summary": "Convert an Office file or image to PDF/A-2b", "description": "Returns the PDF/A-2b bytes of one `.docx`, `.doc`, `.odt`, `.rtf`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.odp`, `.txt`, `.jpg`, `.jpeg` and `.png` file, ready to sign\nlocally or to post as a document. Nothing is stored and nothing is\nbilled. Multipart accepts one binary part named file, up to\n100,000,000 bytes; JSON accepts up to 15 MiB decoded. Added in\nv1.9.0.\n", "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "required": ["file"], "additionalProperties": false, "properties": {"file": {"type": "string", "format": "binary", "description": "One file, at most 100,000,000 bytes. Its extension selects the converter."}}}}, "application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "content": {"type": "string", "format": "byte"}}, "required": ["name", "content"], "additionalProperties": false}}}}, "responses": {"200": {"description": "The converted PDF/A-2b, as an attachment named after the source file with a `.pdf` extension.", "content": {"application/pdf": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "422": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/files/{fileToken}": {"get": {"tags": ["Files"], "operationId": "getFile", "summary": "Inspect a stored file", "parameters": [{"$ref": "#/components/parameters/FileToken"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The stored file.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredFile"}}}}, "404": {"$ref": "#/components/responses/Problem"}}}, "delete": {"tags": ["Files"], "operationId": "deleteFile", "summary": "Purge a stored file", "description": "Drops the bytes. Signings that already referenced the token are\nuntouched, because they hold their own copy.\n", "parameters": [{"$ref": "#/components/parameters/FileToken"}], "responses": {"402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The file, now purged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredFile"}}}}, "404": {"$ref": "#/components/responses/Problem"}}}}, "/v1/me": {"get": {"tags": ["Account"], "operationId": "getMe", "summary": "Who the key acts for", "description": "The workspace and environment this key or connection acts for, and\nthe email of the person it acts as. Automation platforms call it to\ntest a new connection and to name it (v1.12.0).\n", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The workspace behind the key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Me"}}}}}}}, "/v1/webhooks": {"get": {"tags": ["Webhooks"], "operationId": "listWebhooks", "summary": "List webhook subscriptions", "description": "The active webhook subscriptions of this integration (v1.12.0).", "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Active subscriptions, oldest first.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSubscriptionList"}}}}}}, "post": {"tags": ["Webhooks"], "operationId": "createWebhook", "summary": "Subscribe a URL to signing events", "description": "Delivers the chosen events of every signing this integration\ncreates to `url` (the `subscriptionEvent` webhook below). This is\nwhat Zapier, Make and Power Automate call when a user turns a\ntrigger on. The same URL again replaces its event list and returns\nthe same subscription, so a retried subscribe never doubles\ndeliveries. `url` is checked like `webhookUrl`: public HTTPS, at\nmost 500 characters, redirects never followed. An integration holds\nat most 50 subscriptions (v1.12.0).\n", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateWebhookSubscription"}}}}, "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "201": {"description": "Subscribed.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}, "description": "The subscription's URL; DELETE it to unsubscribe."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSubscription"}}}}, "409": {"description": "The integration already holds 50 subscriptions.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}}}, "/v1/webhooks/deliveries": {"get": {"tags": ["Webhooks"], "operationId": "listWebhookDeliveries", "summary": "List recent webhook deliveries", "description": "Returns recent webhook delivery attempts for this API client across\nsigning, headless signature, subscription, form and timestamp channels\n(v1.29.0). Payloads never contain document bytes or personal data.\n", "parameters": [{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending", "delivered", "exhausted", "discarded"]}}, {"name": "event", "in": "query", "schema": {"type": "string", "maxLength": 80}}, {"name": "signingId", "in": "query", "schema": {"type": "string", "format": "uuid"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}], "responses": {"400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Recent webhook delivery attempts, newest first.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookDeliveryList"}}}}}}}, "/v1/webhooks/deliveries/{deliveryId}/retry": {"post": {"tags": ["Webhooks"], "operationId": "retryWebhookDelivery", "summary": "Retry a webhook delivery", "description": "Re-queues a non-delivered webhook event owned by this API client for\nimmediate delivery and extends its retry window (v1.29.0). Already\ndelivered events, events of a removed subscription (unsubscribed or\nanswered `410 Gone`) and a blocked client answer 409. A delivery a\nworker is sending right now also answers 409; its result is recorded\nwithin two minutes.\n", "parameters": [{"$ref": "#/components/parameters/DeliveryId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "202": {"description": "Delivery re-queued.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookDelivery"}}}}}}}, "/v1/webhooks/{webhookId}": {"get": {"tags": ["Webhooks"], "operationId": "getWebhook", "summary": "Get a webhook subscription", "parameters": [{"$ref": "#/components/parameters/WebhookId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "200": {"description": "The subscription.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSubscription"}}}}}}, "delete": {"tags": ["Webhooks"], "operationId": "deleteWebhook", "summary": "Unsubscribe", "description": "Stops deliveries to this subscription and drops its undelivered\nevents. Deleting a subscription that is already removed succeeds\ntoo, so a platform may retry it safely (v1.12.0).\n", "parameters": [{"$ref": "#/components/parameters/WebhookId"}], "responses": {"401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "204": {"description": "Unsubscribed."}}}}, "/v1/timestamps": {"post": {"tags": ["Timestamps"], "operationId": "createTimestamp", "summary": "Put a qualified timestamp on a document, a hash or a web page", "description": "Give exactly one of `document`, `hash` or `page`. Every timestamp is\nqualified and comes from the same pool of qualified timestamp\nauthorities as Tvarka's qualified signatures, unless you send\n`\"qualified\": false` for a document or a hash (a non-qualified\ntimestamp; since 1.23.0). A web page capture is always qualified.\nEach has its own reference code and a public check page (`verifyUrl`).\n\n- `document`: one of `content` (base64, up to 15 MiB), `fileToken`\n  (`POST /v1/files`), `url` (public HTTPS), `markdown` (rendered to an\n  A4 PDF) or `documentId` (a vault document). A PDF comes back as the\n  same PDF with a document timestamp and the authority's chain and\n  OCSP answer (`output: pdf`). Any other file, or a PDF that cannot\n  take an incremental update, comes back as an ASiC-S container with\n  `META-INF/timestamp.tst` (`output: asics`). Answers `201`.\n- `hash`: the SHA-256 of a file you keep. The RFC 3161 token comes back\n  base64 in `token` and as the file (`output: token`). Answers `201`.\n- `page`: a public HTTPS web page. It is opened in headless Chromium,\n  captured as a full-page screenshot with its HTML, and written into a\n  certificate PDF with both files attached, under one document\n  timestamp. Answers `202` with `status: pending`; poll\n  `GET /v1/timestamps/{timestampId}` until `completed` or `failed`.\n  With `page.location` (since 1.24.0) the page is opened through a\n  home internet connection in the chosen country, and optionally a\n  state or a city and a postal code, anywhere in the world. The exit\n  IP address and where it is are recorded in `page.exit` and in the\n  certificate. When no exit in the country can be confirmed, the\n  capture fails with `location_unavailable` and is not charged.\n  Since 1.25.0: `page.locations` (2 to 5 places side by side in one\n  certificate), `page.device` (`desktop` or `mobile`), `page.locale`\n  (the browser language; by default the exit country's),\n  `page.consent: reject` (the cookie test: as opened, then after\n  \"reject all\"), `page.recheckAt` (a recapture then, chained to this\n  one through `previousTimestampId`, with what changed), and\n  `webhookUrl` (`timestamp.completed` / `timestamp.failed`, signed\n  like every Sign API webhook). Every capture records the browser\n  settings, the requests and cookies before any click, the page's\n  embedded data and text, DNS and RDAP facts, the Internet Archive's\n  answer, and a WACZ archive per place\n  (`GET /v1/timestamps/{timestampId}/file?part=p0-archive.wacz`).\n  `secondTimestamp: true` adds a second qualified timestamp from\n  another authority to a page or a PDF.\n\nOne charge per completed timestamp: EUR 0.19 qualified, EUR 0.13\nnon-qualified, EUR 0.49 per place for a page from a chosen location,\nEUR 0.99 for the cookie test, excluding VAT. A failed capture is not charged. `402 payment-required`\nwhen the workspace cannot pay for one; `503 timestamp-unavailable`\nwhen no authority answered (nothing is charged; retry).\n", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateTimestampRequest"}}}}, "responses": {"201": {"description": "The document or the hash is timestamped.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Timestamp"}}}}, "202": {"description": "The web page is queued for capture.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Timestamp"}}}}, "400": {"$ref": "#/components/responses/Problem"}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "413": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}, "get": {"tags": ["Timestamps"], "operationId": "listTimestamps", "summary": "The latest timestamps, newest first", "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, {"name": "monitorId", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid"}}, {"name": "bundleId", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid"}}, {"name": "source", "in": "query", "required": false, "schema": {"type": "string", "enum": ["document", "hash", "page"]}}], "responses": {"200": {"description": "The timestamps.", "content": {"application/json": {"schema": {"type": "object", "properties": {"timestamps": {"type": "array", "items": {"$ref": "#/components/schemas/Timestamp"}}}}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/timestamps/{timestampId}": {"get": {"tags": ["Timestamps"], "operationId": "getTimestamp", "summary": "One timestamp or web page capture", "parameters": [{"$ref": "#/components/parameters/TimestampId"}], "responses": {"200": {"description": "The timestamp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Timestamp"}}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}}}}, "/v1/timestamps/{timestampId}/file": {"get": {"tags": ["Timestamps"], "operationId": "getTimestampFile", "summary": "The timestamped PDF, the ASiC-S container or the token", "parameters": [{"$ref": "#/components/parameters/TimestampId"}], "responses": {"200": {"description": "`application/pdf` (a timestamped PDF or a capture certificate),\n`application/vnd.etsi.asic-s+zip`, or `application/timestamp-reply`\n(the DER token of a hash). `X-Tvarka-Document-Sha256` carries the\nSHA-256 of the body.\n", "content": {"application/pdf": {}, "application/vnd.etsi.asic-s+zip": {}, "application/timestamp-reply": {}}}, "401": {"$ref": "#/components/responses/Problem"}, "402": {"$ref": "#/components/responses/Problem"}, "403": {"$ref": "#/components/responses/Problem"}, "404": {"$ref": "#/components/responses/Problem"}, "503": {"$ref": "#/components/responses/Problem"}, "409": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}}}}}, "webhooks": {"subscriptionEvent": {"post": {"summary": "Webhook subscription event", "description": "Sent to each subscription registered with `POST /v1/webhooks` for\nthe events it chose (v1.12.0). Same headers, HMAC signatures and\n72-hour retry as `signingEvent`, under the same webhook secret.\n`eventId` equals the `X-Tvarka-Idempotency-Key` header: use it to\nprocess each event once. `signing` is the signing at the moment of\nthe event, as `GET /v1/signings/{signingId}` shows it, without\nceremony links. Answer `410 Gone` to remove the subscription.\n", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event": {"$ref": "#/components/schemas/WebhookEventName"}, "eventId": {"type": "string"}, "webhookId": {"type": "string", "format": "uuid"}, "signingId": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SigningStatus"}, "externalId": {"type": "string"}, "occurredAt": {"type": "string", "format": "date-time"}, "completionMode": {"type": "string", "enum": ["qes_ceremony", "esign_ceremony", "sandbox_simulation"]}, "level": {"type": "string", "enum": ["esign"]}, "signer": {"type": "object", "properties": {"signerId": {"type": "string", "format": "uuid"}, "email": {"type": "string", "format": "email"}, "status": {"$ref": "#/components/schemas/SignerStatus"}, "declineReason": {"type": "string"}}}, "document": {"$ref": "#/components/schemas/SignedDocument"}, "signing": {"$ref": "#/components/schemas/Signing"}}, "required": ["event", "eventId", "webhookId", "signingId", "status", "occurredAt", "signing"]}}}}, "responses": {"401": {"$ref": "#/components/responses/Problem"}, "429": {"$ref": "#/components/responses/Problem"}, "200": {"description": "Acknowledged. Any 2xx stops redelivery."}, "410": {"description": "Gone. Tvarka removes the subscription."}}}}}, "components": {"securitySchemes": {"agentOAuth": {"type": "oauth2", "description": "Agent connections for Claude, ChatGPT, Gemini, Copilot and any MCP\nclient. OAuth 2.1 authorization code with PKCE S256, dynamic client\nregistration (RFC 7591) and RFC 9207 `iss` in every authorization\nresponse. Discovery: `/.well-known/oauth-protected-resource/mcp`\n(RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414).\nThe person signs in with their eID, picks the company and allows the\nconnection; the token then acts exactly as that person's own API key\nwould, with the same role re-check on every request. Registration\naccepts the callback URLs of supported agent platforms and loopback\naddresses. Access tokens live one hour; refresh tokens rotate and a\nreused refresh token revokes the connection. The person sees and\nrevokes connections under Settings, API settings, Connected apps.\nHeadless signatures (`/v1/signatures`) are not available to agent\nconnections.\n", "flows": {"authorizationCode": {"authorizationUrl": "https://sign-api.tvarka.pro/oauth/authorize", "tokenUrl": "https://sign-api.tvarka.pro/oauth/token", "refreshUrl": "https://sign-api.tvarka.pro/oauth/token", "scopes": {"sign.read": "Read signings and download signed documents.", "sign.signings": "Send documents for signature, add and remind signers, cancel signings."}}}}, "bearerAuth": {"type": "http", "scheme": "bearer", "description": "`Authorization: Bearer <key>` for REST and MCP. Every active, identified\ncompany member with Sign access has production API access automatically.\nSelect the company, open https://sign.tvarka.pro/sign/app/settings/#api-keys\nand click Show or Copy. The secret is prepared on first use and reused.\nA `tsk_live_` key acts on production; existing `tsk_test_` sandbox keys\nremain supported. Sandbox is retired from ordinary onboarding.\n\nCompany administrators invite users by email and select Employee or\nRepresentative (all rights). The optional email checkbox only requests\nan AES-256 ZIP after identity confirmation; it does not grant API access.\nThe ZIP includes the API key and webhook secret. Its password is the\nlast four personal-code digits, including leading zeroes. Email failure\ndoes not roll back joining the company. Only the owner can reveal keys.\nHistorical hash-only keys remain valid; first Show/Copy prepares a\nrecoverable companion on the same integration. Deliberate revocations\nare never silently undone. Existing integration IDs and history remain.\n\nUsers and access has visible Change rights, Send API key and API settings\nactions without a More menu. A managing employee who may manage payments\ncan administer billing, and one who may manage people can invite others. Pending and failed email\ndelivery appear inline; transport acceptance is not proof of inbox delivery.\n\nManager Replace key gives older keys at most 24 hours of overlap;\nthe successor appears in employee Settings. Manage access offers\nindividual-key revocation, whole-integration revocation, immediate\nreplacement, planned rotation and webhook-secret changes. Advanced\nreplacement, planned rotation and webhook-secret changes require\nrecent eID confirmation. Rotation/revocation leaves the webhook secret\nunchanged unless it is explicitly changed separately.\n\nThe key acts as a named workspace user. Removing that person's role\npermanently revokes its API access; restoring the role does not revive\nkeys. Suspended access blocks API use. Revocation stops the affected\nkeys immediately but does not cancel already-created signing orders.\nATK and Due Diligence credentials are separate. Full guidance:\nhttps://sign-api.tvarka.pro/docs#keys.\n"}, "apiKeyHeader": {"type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "The same API key as `bearerAuth`, in its own header, for platforms\nwhose API key connections send a key exactly as typed (v1.12.0).\nSend one of the two, not both.\n"}}, "parameters": {"IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional tenant-and-operation-scoped create key (1-128 visible ASCII characters). Identical input replays the original response; changed input or an unresolved execution returns 409. After 90 days the response expires but the key remains reserved. Do not change keys to retry a request with an uncertain outcome.", "schema": {"type": "string", "minLength": 1, "maxLength": 128}}, "FileToken": {"name": "fileToken", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "TimestampId": {"name": "timestampId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "WebhookId": {"name": "webhookId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "DeliveryId": {"name": "deliveryId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}}, "responses": {"Problem": {"description": "An RFC 9457 problem document.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}, "schemas": {"CapturePageOptions": {"type": "object", "additionalProperties": false, "properties": {"location": {"$ref": "#/components/schemas/CreateTimestampRequest/properties/page/properties/location"}, "locations": {"$ref": "#/components/schemas/CreateTimestampRequest/properties/page/properties/locations"}, "device": {"type": "string", "enum": ["desktop", "mobile"], "default": "desktop"}, "locale": {"type": "string"}, "consent": {"type": "string", "enum": ["reject"]}}}, "CreateCaptureMonitor": {"type": "object", "additionalProperties": false, "required": ["page"], "properties": {"page": {"type": "object", "additionalProperties": false, "required": ["url"], "properties": {"url": {"type": "string", "format": "uri"}, "location": {"$ref": "#/components/schemas/CapturePageOptions/properties/location"}, "locations": {"$ref": "#/components/schemas/CapturePageOptions/properties/locations"}, "device": {"$ref": "#/components/schemas/CapturePageOptions/properties/device"}, "locale": {"type": "string"}, "consent": {"type": "string", "enum": ["reject"]}}, "description": "Shared capture options plus required url; recheckAt is not accepted."}, "everyHours": {"type": "integer", "minimum": 1, "maximum": 2160, "default": 24}, "maxCaptures": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 30}, "endsAt": {"type": "string", "format": "date-time", "description": "Optional earlier end of the schedule."}, "title": {"type": "string", "maxLength": 255}, "externalId": {"type": "string", "maxLength": 120}, "webhookUrl": {"type": "string", "format": "uri"}, "language": {"type": "string", "default": "en"}, "secondTimestamp": {"type": "boolean", "default": false}}}, "CaptureMonitor": {"type": "object", "properties": {"monitorId": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["active", "paused", "completed"]}, "page": {"type": "object"}, "everyHours": {"type": "integer"}, "maxCaptures": {"type": "integer"}, "captureCount": {"type": "integer"}, "pricePerCaptureCents": {"type": "integer", "description": "Current workspace price excluding VAT, zero in sandbox."}, "currency": {"type": "string", "const": "EUR"}, "nextCaptureAt": {"type": ["string", "null"], "format": "date-time"}, "endsAt": {"type": ["string", "null"], "format": "date-time"}, "latestTimestampId": {"type": ["string", "null"], "format": "uuid"}, "failureReason": {"type": ["string", "null"]}}}, "CreateCaptureBundle": {"type": "object", "additionalProperties": false, "required": ["urls"], "properties": {"urls": {"type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": {"type": "string", "format": "uri"}}, "page": {"$ref": "#/components/schemas/CapturePageOptions"}, "title": {"type": "string", "maxLength": 255}, "externalId": {"type": "string", "maxLength": 120}, "webhookUrl": {"type": "string", "format": "uri"}, "language": {"type": "string", "default": "en"}, "secondTimestamp": {"type": "boolean", "default": false}}}, "CaptureBundle": {"type": "object", "properties": {"bundleId": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "externalId": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "completed"]}, "sealedAt": {"type": ["string", "null"], "format": "date-time"}, "manifestSha256": {"type": ["string", "null"]}, "fileUrl": {"type": ["string", "null"], "format": "uri"}, "captures": {"type": "array", "items": {"$ref": "#/components/schemas/Timestamp"}}}}, "CaptureQuality": {"type": "object", "description": "Observed conditions, not a guarantee of complete website collection. Per-place quality also includes location match results.", "required": ["status", "reasons"], "properties": {"status": {"type": "string", "enum": ["pending", "unknown", "captured", "partial", "challenge", "login_required", "unavailable"]}, "reasons": {"type": "array", "items": {"type": "string"}}, "location": {"type": "object", "additionalProperties": {"type": "string", "enum": ["matched", "mismatch", "unverified"]}}, "failedRequests": {"type": "integer", "minimum": 0}, "method": {"type": "string"}}}, "CreateTimestampRequest": {"type": "object", "additionalProperties": false, "properties": {"document": {"type": "object", "additionalProperties": false, "description": "Exactly one of content, fileToken, url, markdown or documentId.", "properties": {"content": {"type": "string", "contentEncoding": "base64"}, "fileToken": {"type": "string"}, "url": {"type": "string", "format": "uri"}, "markdown": {"type": "string"}, "documentId": {"type": "string", "format": "uuid"}, "name": {"type": "string", "maxLength": 120, "description": "The file name kept inside the result."}}}, "hash": {"type": "object", "additionalProperties": false, "required": ["algorithm", "value"], "properties": {"algorithm": {"type": "string", "enum": ["sha256"]}, "value": {"type": "string", "contentEncoding": "base64", "description": "The 32-byte SHA-256 digest."}}}, "page": {"type": "object", "additionalProperties": false, "required": ["url"], "properties": {"url": {"type": "string", "format": "uri", "description": "A public HTTPS address."}, "location": {"type": "object", "additionalProperties": false, "required": ["country"], "description": "Open the page from this place. A state and a city cannot both be given.", "properties": {"country": {"type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2, such as DE."}, "state": {"type": "string", "maxLength": 80, "description": "A state or region, such as California."}, "city": {"type": "string", "maxLength": 80, "description": "A city, such as Berlin."}, "zip": {"type": "string", "maxLength": 20, "description": "A postal code, such as 10001."}}}, "locations": {"type": "array", "minItems": 2, "maxItems": 5, "description": "Compare the page from 2 to 5 places; each like location. Not with location.", "items": {"type": "object", "required": ["country"], "properties": {"country": {"type": "string"}, "state": {"type": "string"}, "city": {"type": "string"}, "zip": {"type": "string"}}}}, "device": {"type": "string", "enum": ["desktop", "mobile"], "default": "desktop"}, "locale": {"type": "string", "description": "The browser language, such as de-DE."}, "consent": {"type": "string", "enum": ["reject"], "description": "The cookie test. One place at most."}, "recheckAt": {"type": "string", "format": "date-time", "description": "1 hour to 90 days ahead."}}}, "webhookUrl": {"type": "string", "format": "uri", "description": "Public HTTPS; timestamp.completed or timestamp.failed."}, "secondTimestamp": {"type": "boolean", "default": false, "description": "A second qualified timestamp from another authority (a page or a PDF)."}, "language": {"type": "string", "default": "en", "description": "Language of a web page capture certificate, such as en, de, fr or lt."}, "qualified": {"type": "boolean", "default": true, "description": "false takes a non-qualified timestamp (document or hash only)."}, "title": {"type": "string", "maxLength": 255}, "externalId": {"type": "string", "maxLength": 120}}}, "Timestamp": {"type": "object", "properties": {"timestampId": {"type": "string", "format": "uuid"}, "code": {"type": "string", "description": "The reference code, TVK-XXXX-XXXX-XXXX-XXXX-C."}, "verifyUrl": {"type": "string", "format": "uri", "description": "The public check page."}, "source": {"type": "string", "enum": ["document", "hash", "page"]}, "status": {"type": "string", "enum": ["pending", "capturing", "completed", "failed"]}, "output": {"type": ["string", "null"], "enum": ["pdf", "asics", "token", null]}, "title": {"type": ["string", "null"]}, "externalId": {"type": ["string", "null"]}, "sha256": {"type": ["string", "null"], "description": "The SHA-256 of what was timestamped (hex)."}, "outputSha256": {"type": ["string", "null"], "description": "The SHA-256 of the delivered file (hex)."}, "timestampedAt": {"type": ["string", "null"], "format": "date-time", "description": "The time in the token."}, "qualified": {"type": "boolean", "description": "false for a non-qualified timestamp."}, "previousTimestampId": {"type": "string", "format": "uuid", "description": "The capture this recapture follows."}, "monitorId": {"type": "string", "format": "uuid"}, "bundleId": {"type": "string", "format": "uuid"}, "exhibit": {"type": "integer", "minimum": 1}, "secondTimestampAt": {"type": ["string", "null"], "format": "date-time"}, "longTermProof": {"type": ["boolean", "null"], "description": "For a PDF, whether the chain and OCSP answer are inside."}, "token": {"type": "string", "contentEncoding": "base64", "description": "Hash only: the DER TimeStampToken."}, "fileUrl": {"type": ["string", "null"], "format": "uri"}, "createdAt": {"type": "string", "format": "date-time"}, "completedAt": {"type": ["string", "null"], "format": "date-time"}, "page": {"type": "object", "properties": {"quality": {"$ref": "#/components/schemas/CaptureQuality"}, "url": {"type": "string"}, "finalUrl": {"type": ["string", "null"]}, "httpStatus": {"type": ["integer", "null"]}, "title": {"type": ["string", "null"]}, "capturedAt": {"type": ["string", "null"], "format": "date-time"}, "screenshotSha256": {"type": ["string", "null"]}, "htmlSha256": {"type": ["string", "null"]}, "location": {"type": ["object", "null"], "description": "The place asked for.", "properties": {"country": {"type": "string"}, "state": {"type": "string"}, "city": {"type": "string"}, "zip": {"type": "string"}}}, "device": {"type": "string"}, "consent": {"type": "string"}, "recheckAt": {"type": "string", "format": "date-time"}, "places": {"type": ["array", "null"], "description": "One entry per place - location, exit, persona (browser settings), finalUrl, httpStatus, title, hashes, embedded data, audit (opened / afterReject), consent, archive, changes.", "items": {"type": "object"}}, "site": {"type": ["object", "null"], "description": "host, domain, dns (A, AAAA), rdap (registrant, registrar, registered, expires, nameservers)."}, "internetArchive": {"type": ["object", "null"], "description": "url, status, at."}, "archives": {"type": ["array", "null"], "items": {"type": "object", "properties": {"name": {"type": "string"}, "sha256": {"type": "string"}, "bytes": {"type": "integer"}, "fileUrl": {"type": "string", "format": "uri"}}}}, "exit": {"type": ["object", "null"], "description": "The exit the capture was checked to leave through, as an IP lookup service reports it.", "properties": {"ip": {"type": "string"}, "country": {"type": "string"}, "region": {"type": "string"}, "city": {"type": "string"}, "postal": {"type": "string"}, "network": {"type": "string"}}}}}, "failure": {"type": "object", "properties": {"reason": {"type": "string"}, "detail": {"type": ["string", "null"]}}}}}, "VisibleSignature": {"description": "Any workspace may place this signer's visible PDF stamp. Use\neither page coordinates in PDF points from the lower-left MediaBox\ncorner, or one existing unsigned signature field. The accepted value\nis immutable and returned on the signer. PDF only; field binding cannot\nbe combined with `document.flatten: true`.\n`page` is 1-based. Coordinates are finite PDF points (1/72 inch) in\nunrotated page space; x/y are offsets even when the MediaBox origin is\nnonzero. The whole box must fit MediaBox and CropBox. Minimum size is\n148 x 52 pt; placement requires /UserUnit: 1. A field must have\none usable visible widget, be unsigned and unlocked, and meet the\nsame geometry rules. Earlier field locks, ambiguous names and fields\nalready reserved for another signer are rejected. Explicit positions\ndo not become cascade anchors. Do not send this property for viewers.\nNo entitlement is needed (v1.13.1); the company logo and VIP\nwhitelabel are separate. Omit the property to use normal corner\nplacement; configured workspace branding still applies.\n", "examples": [{"page": 1, "x": 36, "y": 36, "width": 148, "height": 52}, {"field": "Sig_Vadovas"}], "oneOf": [{"type": "object", "properties": {"page": {"type": "integer", "minimum": 1}, "x": {"type": "number", "minimum": 0}, "y": {"type": "number", "minimum": 0}, "width": {"type": "number", "minimum": 148}, "height": {"type": "number", "minimum": 52}}, "required": ["page", "x", "y", "width", "height"], "additionalProperties": false}, {"type": "object", "properties": {"field": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["field"], "additionalProperties": false}, {"type": "object", "description": "Smart anchor placement (v1.29.0): searches the PDF text for `anchor`\n(exact case-sensitive match first, diacritic-folded case-insensitive\nfallback) and places the stamp at the anchor baseline shifted by\noptional `offsetX` / `offsetY`. Supported on both `qualified` and\n`esign` signings and headless `pades` signatures.\n", "properties": {"anchor": {"type": "string", "minLength": 1, "maxLength": 120}, "offsetX": {"type": "number", "default": 0}, "offsetY": {"type": "number", "default": 0}, "width": {"type": "number", "minimum": 148, "default": 148}, "height": {"type": "number", "minimum": 52, "default": 52}, "occurrence": {"default": "first", "oneOf": [{"type": "string", "enum": ["first", "last"]}, {"type": "integer", "minimum": 1, "maximum": 100}]}}, "required": ["anchor"], "additionalProperties": false}]}, "TemplateVisibleSignature": {"description": "A box saved on a template role, and the box a signer gets from it\n(v1.14.1). The shape of `VisibleSignature`. The sizes are those of\nthe template's level, the sizes the Tvarka Sign app saves it with:\nat least the default qualified stamp (103.18 x 35.72 pt) or the\ndefault e-signature mark (119.06 x 45.64 pt), and at most three\ntimes that. When a qualified template is sent, the box is checked\nby these sizes and must fit the PDF. A box sent to `POST /v1/templates` is\na box sent in a request, so it keeps the `VisibleSignature` rules,\n148 x 52 pt at least. A field binding keeps the field rules of\n`VisibleSignature`.\n", "examples": [{"page": 1, "x": 60, "y": 120, "width": 103.18, "height": 35.72}, {"field": "Sig_Vadovas"}], "oneOf": [{"type": "object", "properties": {"page": {"type": "integer", "minimum": 1}, "x": {"type": "number", "minimum": 0}, "y": {"type": "number", "minimum": 0}, "width": {"type": "number", "exclusiveMinimum": 0}, "height": {"type": "number", "exclusiveMinimum": 0}}, "required": ["page", "x", "y", "width", "height"], "additionalProperties": false}, {"type": "object", "properties": {"field": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["field"], "additionalProperties": false}, {"type": "object", "properties": {"anchor": {"type": "string", "minLength": 1, "maxLength": 120}, "offsetX": {"type": "number", "default": 0}, "offsetY": {"type": "number", "default": 0}, "width": {"type": "number", "exclusiveMinimum": 0}, "height": {"type": "number", "exclusiveMinimum": 0}, "occurrence": {"default": "first", "oneOf": [{"type": "string", "enum": ["first", "last"]}, {"type": "integer", "minimum": 1, "maximum": 100}]}}, "required": ["anchor"], "additionalProperties": false}]}, "Me": {"type": "object", "properties": {"workspace": {"type": "object", "properties": {"name": {"type": "string"}, "country": {"type": "string", "description": "ISO 3166-1 alpha-2."}}, "required": ["name", "country"]}, "environment": {"type": "string", "enum": ["production", "sandbox"]}, "user": {"type": "object", "properties": {"email": {"type": "string", "format": "email"}}, "required": ["email"]}}, "required": ["workspace", "environment", "user"]}, "WebhookEventName": {"type": "string", "enum": ["signing.approver_approved", "signing.approver_declined", "signing.signer_signed", "signing.signer_declined", "signing.signer_failed", "signing.completed", "signing.declined", "signing.cancelled", "signing.expired", "signing.failed", "form_request.opened", "form_request.submitted", "form_request.completed", "form_request.cancelled", "form_request.expired", "form_request.failed"]}, "CreateWebhookSubscription": {"type": "object", "properties": {"url": {"type": "string", "format": "uri", "maxLength": 500}, "events": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/components/schemas/WebhookEventName"}}}, "required": ["url", "events"], "additionalProperties": false}, "WebhookSubscription": {"type": "object", "properties": {"webhookId": {"type": "string", "format": "uuid"}, "url": {"type": "string", "format": "uri"}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookEventName"}}, "createdAt": {"type": "string", "format": "date-time"}}, "required": ["webhookId", "url", "events", "createdAt"]}, "WebhookSubscriptionList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookSubscription"}}}, "required": ["data"]}, "WebhookDelivery": {"type": "object", "properties": {"deliveryId": {"type": "string", "format": "uuid"}, "channel": {"type": "string", "enum": ["sign", "sign_sig", "sign_hook", "sign_form", "sign_ts"]}, "event": {"type": "string"}, "resourceId": {"type": "string", "format": "uuid"}, "signingId": {"type": ["string", "null"], "format": "uuid"}, "signerId": {"type": ["string", "null"], "format": "uuid"}, "callbackUrl": {"type": "string", "format": "uri"}, "status": {"type": "string", "enum": ["pending", "delivered", "exhausted", "discarded"]}, "attempts": {"type": "integer", "minimum": 0}, "lastError": {"type": ["string", "null"]}, "discardReason": {"type": ["string", "null"]}, "createdAt": {"type": "string", "format": "date-time"}, "deliveredAt": {"type": ["string", "null"], "format": "date-time"}, "nextAttemptAt": {"type": ["string", "null"], "format": "date-time"}, "exhaustedAt": {"type": ["string", "null"], "format": "date-time"}, "discardedAt": {"type": ["string", "null"], "format": "date-time"}, "payload": {"type": ["object", "string", "null"], "additionalProperties": true}}, "required": ["deliveryId", "channel", "event", "resourceId", "callbackUrl", "status", "attempts", "createdAt"]}, "WebhookDeliveryList": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookDelivery"}}, "hasMore": {"type": "boolean"}}, "required": ["data", "hasMore"]}, "Signing": {"type": "object", "properties": {"signingId": {"type": "string", "format": "uuid"}, "status": {"$ref": "#/components/schemas/SigningStatus"}, "level": {"type": "string", "enum": ["qualified", "esign"]}, "processingStage": {"type": "string", "enum": ["awaiting_approvers", "awaiting_signers", "finalizing"], "description": "While `pending`: `awaiting_approvers` while pre-sign approvers are\nopen, `awaiting_signers` while signers can still sign, or\n`finalizing` once every signer slot is satisfied and the file is\nbeing sealed (a simple e-signature's document timestamp).\n"}, "title": {"type": "string"}, "delivery": {"type": "string", "enum": ["link", "email"]}, "signingOrder": {"type": "string", "enum": ["parallel", "sequential"], "description": "`sequential` releases one signer at a time in the order they were\nposted. The signers who are waiting hold a ceremony link that\nanswers 404 until their turn, so the ordering is enforced rather\nthan merely unsent. A decline stops the workflow at the\ndecliner's turn: the signing settles `declined` and the signers\nstill waiting are cancelled.\n"}, "softDeadlineAt": {"type": ["string", "null"], "format": "date-time", "description": "The date the signing is wanted by, as opposed to `expiresAt`,\nwhich is the date it dies on. Nothing expires here; it is when the\none automatic reminder goes out.\n"}, "externalId": {"type": ["string", "null"]}, "templateId": {"type": "string", "format": "uuid", "description": "Present when the signing was sent from a template (v1.14.0)."}, "embedOrigin": {"type": "string", "format": "uri", "description": "Present when the signing permits iframe embedding on a registered HTTPS origin (v1.29.0)."}, "createdAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": ["string", "null"], "format": "date-time"}, "completedAt": {"type": ["string", "null"], "format": "date-time"}, "completionMode": {"type": ["string", "null"], "enum": ["qes_ceremony", "esign_ceremony", "sandbox_simulation", null], "description": "`qes_ceremony` means human eID signing. `esign_ceremony` means a\ncompleted simple e-signature. `sandbox_simulation`\nexercises lifecycle/webhook integration and creates no\nsignature; its artifact is flagged `sandbox: true`.\n"}, "erasedAt": {"type": ["string", "null"], "format": "date-time"}, "detail": {"type": "string", "description": "Present when the status needs a sentence of explanation."}, "signers": {"type": "array", "items": {"$ref": "#/components/schemas/Signer"}}, "document": {"$ref": "#/components/schemas/SignedDocument"}, "authority": {"type": "object", "description": "Present when the signing named the company its signers sign for\n(MCP `entityCode`, v1.19.0). Once the signing completes, each\nsigner's personal code from their qualified signature is matched\nagainst the vadovas recorded in JAR. `recordedRole` is `vadovas`\nor null. Billed once, as a Tvarka Due Diligence JAR extract.\n", "properties": {"entityCode": {"type": "string"}, "register": {"type": "string", "enum": ["JAR"]}, "status": {"type": "string", "enum": ["pending", "checked", "unavailable"]}, "checkedAt": {"type": "string", "format": "date-time"}, "entityFound": {"type": "boolean"}, "sandbox": {"type": "boolean"}, "signers": {"type": "array", "items": {"type": "object", "properties": {"email": {"type": "string"}, "recordedRole": {"type": ["string", "null"], "enum": ["vadovas", null]}, "detail": {"type": "string", "enum": ["identity_unavailable"]}}}}}}, "evidence": {"type": "object", "description": "A completed simple e-signature (`level: esign`).", "properties": {"available": {"type": "boolean", "description": "False once erased."}, "referenceCode": {"type": "string"}, "verificationUrl": {"type": "string", "format": "uri"}, "separateSummary": {"type": "boolean"}, "sealedAt": {"type": ["string", "null"], "format": "date-time"}, "sandbox": {"type": "boolean"}, "validation": {"type": "object", "properties": {"status": {"type": "string", "enum": ["notApplicable"]}}}}}}}, "Signer": {"type": "object", "properties": {"signerId": {"type": "string", "format": "uuid"}, "role": {"type": "string", "enum": ["signer", "approver", "cc", "viewer"], "description": "`signer` signs the document; `approver` reviews and approves before\nsigning begins; `cc` receives the finished signed document copy by\nemail once signing completes; `viewer` is recorded only and Tvarka\nsends them nothing. At least one signer is required.\n"}, "group": {"type": "string", "maxLength": 64, "description": "Recipient group name when this signer belongs to an \"any 1 of N\" group."}, "email": {"type": ["string", "null"], "format": "email"}, "name": {"type": ["string", "null"]}, "language": {"type": "string", "enum": ["lt", "en", "et", "lv", "pl", "uk", "ru", "de", "fr", "es", "it", "nl", "sv", "da", "nb", "fi"]}, "status": {"$ref": "#/components/schemas/SignerStatus"}, "ceremonyUrl": {"type": "string", "format": "uri", "description": "Present only while this signer (`role: signer`) can still sign. A\nfinished or retracted invitation has no live URL.\n"}, "approvalUrl": {"type": "string", "format": "uri", "description": "Present only while this pre-sign approver (`role: approver`) is\n`pending`. Cleared once approved, declined, cancelled, or expired.\n"}, "approvedAt": {"type": ["string", "null"], "format": "date-time"}, "ccNotifiedAt": {"type": ["string", "null"], "format": "date-time"}, "signedAt": {"type": ["string", "null"], "format": "date-time"}, "declinedAt": {"type": ["string", "null"], "format": "date-time"}, "declineReason": {"type": "string"}, "methodsAllowed": {"type": "array", "items": {"$ref": "#/components/schemas/SigningMethod"}}, "actualMethod": {"oneOf": [{"$ref": "#/components/schemas/SigningMethod"}, {"type": "null"}], "description": "Present after a real signature; contains no identity data."}, "identityLocked": {"type": "boolean"}, "authentication": {"type": "object", "description": "`level: esign` signers: the protection type only, never the code.", "properties": {"type": {"type": "string", "enum": ["email_link", "access_code", "sms"]}}}, "signingPurpose": {"type": ["string", "null"], "enum": ["signature", "confirmation", "visa", "registration", null], "description": "Accepted immutable purpose; null for a viewer."}, "visibleSignature": {"description": "The accepted placement, or null. A signer of a signing sent from\na template carries the role's saved box (`TemplateVisibleSignature`,\nv1.14.1).\n", "anyOf": [{"$ref": "#/components/schemas/VisibleSignature"}, {"$ref": "#/components/schemas/TemplateVisibleSignature"}, {"type": "null"}]}, "identityMatched": {"type": ["boolean", "null"], "description": "True only after a locked signer completes the real ceremony."}, "simulatedAt": {"type": ["string", "null"], "format": "date-time"}, "emailStatus": {"type": "string", "enum": ["not_requested", "pending", "accepted", "failed", "cancelled", "unknown"], "description": "Initial invitation email state. Accepted means the email backend\naccepted the message, not inbox delivery. Unknown denotes legacy\nbest-effort delivery whose outcome was not recorded. Sequential\nsigners stay not_requested until their turn is released.\n"}, "emailAcceptedAt": {"type": ["string", "null"], "format": "date-time"}}}, "StoredFile": {"type": "object", "properties": {"fileToken": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "mediaType": {"type": "string"}, "sha256": {"type": "string"}, "bytes": {"type": "integer"}, "createdAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": "string", "format": "date-time", "description": "An unreferenced upload is not kept forever just because nobody\ndeleted it. Re-upload after this, or post the bytes inline.\n"}, "usedCount": {"type": "integer", "description": "How many signings have copied these bytes."}}}, "SignedDocument": {"type": "object", "description": "The newest signed output. Absent until somebody signs, except on a\nsandbox simulation, where it describes the unsigned artifact.\n", "properties": {"sha256": {"type": "string"}, "bytes": {"type": "integer"}, "mimeType": {"type": "string"}, "sandbox": {"type": "boolean", "description": "Present and true only on a sandbox simulation. The bytes are a\nreal file to which no signature was added.\n"}, "signed": {"type": "boolean", "description": "Present and false only on a sandbox simulation. Absent on a real\nsigning, where the output is signed by definition.\n"}}}, "SigningStatus": {"type": "string", "enum": ["pending", "completed", "declined", "cancelled", "expired", "failed"], "description": "`pending` - at least one signer can still sign.\n`completed` - every signer signed.\n`declined` - somebody declined and nobody else can still sign.\n`expired` - the window closed first.\n`cancelled` - you retracted it.\n`failed` - the signing could not be prepared.\n"}, "SignerStatus": {"type": "string", "enum": ["pending", "signed", "approved", "declined", "cancelled", "expired", "failed", "simulated", "waiting", "recorded"], "description": "`waiting` - a sequential signer/approver whose turn has not come, or a\nsigner parked while pre-sign approvers review; their link answers 404\nuntil released.\n`approved` - a pre-sign approver who approved the document.\n`failed` - the signer's requested PDF stamp could not be prepared.\n`recorded` - a `cc` or `viewer` party. Never blocks completion.\n"}, "SigningMethod": {"type": "string", "enum": ["nfc", "smart_id", "mobile_id"], "description": "The orchestration methods. For direct LT ATK reader, USB, raw CAdES\nand lower-level NFC integration, use the ATK API.\n"}, "ProblemFieldError": {"type": "object", "description": "One rejected field.", "properties": {"code": {"type": "string", "description": "Stable signing refusal code on a document-not-signable response."}, "pointer": {"type": "string", "description": "RFC 6901 JSON Pointer into the request body, for example\n`/signers/0/email` or `/container/files/2/content`.\n"}, "detail": {"type": "string"}}, "required": ["pointer", "detail"]}, "Problem": {"type": "object", "description": "RFC 9457.", "properties": {"final": {"type": "boolean", "description": "True for a definitive document-not-signable refusal."}, "type": {"type": "string", "format": "uri"}, "title": {"type": "string"}, "status": {"type": "integer"}, "detail": {"type": "string"}, "errors": {"type": "array", "description": "Present on `validation-failed`, and on the single-fault problems\nthat name a field. Request-body validation collects rather than\nfailing fast, so a caller who got three fields wrong learns all\nthree from one response.\n", "items": {"$ref": "#/components/schemas/ProblemFieldError"}}, "recoveryUrl": {"type": "string", "format": "uri-reference", "description": "Present on the payment-required refusal when a web page exists\nthat fixes it: the tenant's payment setup, reached with an\nordinary browser login. Show it to your operator; it is not an\nAPI endpoint.\n"}, "billingContext": {"type": "object", "description": "Present on order-time payment-required refusals. Identifies the\ncompany fixed to the API key, regardless of browser workspace.\nPayment arrangements require an active company administrator (manager or managing employee who may manage payments).\n", "required": ["workspaceId", "companyCode", "companyName", "canManageBilling"], "properties": {"workspaceId": {"type": "string", "format": "uuid"}, "companyCode": {"type": "string"}, "companyName": {"type": "string"}, "canManageBilling": {"type": "boolean"}}}}}}}}