{ "components": { "examples": { "ArtifactLink": { "value": { "artifactId": "44444444-4444-4444-8444-444444444444", "contractVersion": "publishing.lifecycle.v1", "expiresAt": "2026-07-20T12:16:00.000Z", "href": "https://storage.example.invalid/object?token=short-lived-example", "retention": { "deleteRequestedAt": null, "deletedAt": null, "expiresAt": "2026-07-27T12:10:04.000Z", "policy": "managed_default" } } }, "CreateWebhookRequest": { "value": { "description": "Production publishing events", "endpoint": "https://hooks.example.com/markdowntopdf", "eventTypes": [ "job.succeeded", "job.failed", "job.cancelled" ] } }, "ConflictError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "conflict", "code": "idempotency_conflict", "httpStatus": 409, "message": "This idempotency key was already used with a different request.", "retryable": false } } }, "CreateDocumentRequest": { "value": { "revision": { "markdown": "# Northstar Launch Brief\n\n## Decision\nApprove the measured rollout.", "parentRevisionId": null, "spec": { "locale": "en", "options": { "pageNumbers": true }, "templateId": "executive" } }, "taskId": "executive-brief", "title": "Northstar Launch Brief" } }, "CreateRevisionRequest": { "value": { "markdown": "# Northstar Launch Brief\n\n## Decision\nApprove the measured rollout with a staged release.", "parentRevisionId": "22222222-2222-4222-8222-222222222222", "spec": { "locale": "en", "options": { "pageNumbers": true }, "templateId": "executive" } } }, "DeletionAccepted": { "value": { "contractVersion": "publishing.lifecycle.v1", "documentId": "11111111-1111-4111-8111-111111111111", "retention": { "deleteRequestedAt": "2026-07-20T12:20:00.000Z", "deletedAt": null, "expiresAt": "2026-08-19T12:00:00.000Z", "policy": "managed_default" }, "status": "accepted" } }, "DocumentCreated": { "value": { "contractVersion": "publishing.lifecycle.v1", "document": { "createdAt": "2026-07-20T12:00:00.000Z", "id": "11111111-1111-4111-8111-111111111111", "lastActivityAt": "2026-07-20T12:00:00.000Z", "latestRevisionId": "22222222-2222-4222-8222-222222222222", "locale": "en", "retention": { "deleteRequestedAt": null, "deletedAt": null, "expiresAt": "2026-08-19T12:00:00.000Z", "policy": "managed_default" }, "status": "active", "taskId": "executive-brief", "title": "Northstar Launch Brief", "updatedAt": "2026-07-20T12:00:00.000Z" }, "links": { "preview": "/api/v2/documents/11111111-1111-4111-8111-111111111111/previews", "publish": "/api/v2/documents/11111111-1111-4111-8111-111111111111/publishes", "revisions": "/api/v2/documents/11111111-1111-4111-8111-111111111111/revisions", "self": "/api/v2/documents/11111111-1111-4111-8111-111111111111" }, "revision": { "createdAt": "2026-07-20T12:00:00.000Z", "documentId": "11111111-1111-4111-8111-111111111111", "id": "22222222-2222-4222-8222-222222222222", "parentRevisionId": null, "sequence": 1, "sourceBytes": 74, "sourceSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "specSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } } }, "DocumentDetail": { "value": { "contractVersion": "publishing.lifecycle.v1", "document": { "createdAt": "2026-07-20T12:00:00.000Z", "id": "11111111-1111-4111-8111-111111111111", "lastActivityAt": "2026-07-20T12:10:00.000Z", "latestRevisionId": "22222222-2222-4222-8222-222222222222", "locale": "en", "retention": { "deleteRequestedAt": null, "deletedAt": null, "expiresAt": "2026-08-19T12:10:00.000Z", "policy": "managed_default" }, "status": "active", "taskId": "executive-brief", "title": "Northstar Launch Brief", "updatedAt": "2026-07-20T12:10:00.000Z" }, "latestRevision": { "createdAt": "2026-07-20T12:00:00.000Z", "documentId": "11111111-1111-4111-8111-111111111111", "id": "22222222-2222-4222-8222-222222222222", "parentRevisionId": null, "sequence": 1, "sourceBytes": 74, "sourceSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "specSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "links": { "preview": "/api/v2/documents/11111111-1111-4111-8111-111111111111/previews", "publish": "/api/v2/documents/11111111-1111-4111-8111-111111111111/publishes", "revisions": "/api/v2/documents/11111111-1111-4111-8111-111111111111/revisions", "self": "/api/v2/documents/11111111-1111-4111-8111-111111111111" } } }, "DocumentList": { "value": { "contractVersion": "publishing.lifecycle.v1", "documents": [ { "createdAt": "2026-07-20T12:00:00.000Z", "id": "11111111-1111-4111-8111-111111111111", "lastActivityAt": "2026-07-20T12:10:00.000Z", "latestRevisionId": "22222222-2222-4222-8222-222222222222", "locale": "en", "retention": { "deleteRequestedAt": null, "deletedAt": null, "expiresAt": "2026-08-19T12:10:00.000Z", "policy": "managed_default" }, "status": "active", "taskId": "executive-brief", "title": "Northstar Launch Brief", "updatedAt": "2026-07-20T12:10:00.000Z" } ], "pagination": { "hasMore": false, "nextCursor": null } } }, "ForbiddenError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "authorization", "code": "forbidden", "httpStatus": 403, "message": "The API key does not have the required scope.", "retryable": false } } }, "GoneError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "storage", "code": "artifact_expired", "httpStatus": 410, "message": "The artifact has expired and is no longer downloadable.", "retryable": false } } }, "InvalidRequestError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "input", "code": "invalid_request", "httpStatus": 400, "message": "The request did not match the v2 contract.", "retryable": false } } }, "JobAccepted": { "value": { "artifact": null, "contractVersion": "publishing.lifecycle.v1", "job": { "acceptedAt": "2026-07-20T12:10:00.000Z", "artifactId": null, "attemptCount": 0, "completedAt": null, "documentId": "11111111-1111-4111-8111-111111111111", "entitlement": { "capturedAt": "2026-07-20T12:10:00.000Z", "catalogVersion": "2026-07-20.1", "plan": "free", "source": "free_trial", "units": 1 }, "error": null, "id": "33333333-3333-4333-8333-333333333333", "outputFormat": "pdf", "provenance": { "assetSetSha256": null, "catalogSha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "catalogVersion": "2026-07-20.1", "channel": "rest_v2", "engineVersion": "1.0.1", "fontSetSha256": null, "locale": "en", "manifestSha256": null, "optionsSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "renderOptionsSha256": null, "rendererReleaseChecksum": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "rendererVersion": "gotenberg-8.34.0", "requestSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "sourceSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "synthetic": false, "templateDefinitionSha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "templateId": "executive", "templateReleaseId": "44444444-4444-4444-8444-444444444444", "templateReleaseSha256": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" }, "purpose": "final", "queuedAt": "2026-07-20T12:10:01.000Z", "requestSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "retention": { "deleteRequestedAt": null, "deletedAt": null, "expiresAt": "2026-07-27T12:10:00.000Z", "policy": "managed_default" }, "revisionId": "22222222-2222-4222-8222-222222222222", "startedAt": null, "status": "queued" }, "links": { "cancel": "/api/v2/jobs/33333333-3333-4333-8333-333333333333/cancel", "self": "/api/v2/jobs/33333333-3333-4333-8333-333333333333" }, "warnings": [] } }, "NotFoundError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "authorization", "code": "not_found", "httpStatus": 404, "message": "The requested resource was not found.", "retryable": false } } }, "PreviewRequest": { "value": { "output": { "filename": "northstar-launch-brief-preview.pdf", "format": "pdf" }, "revisionId": "22222222-2222-4222-8222-222222222222" } }, "PreviewJobAccepted": { "value": { "artifact": null, "contractVersion": "publishing.lifecycle.v1", "job": { "acceptedAt": "2026-07-20T12:08:00.000Z", "artifactId": null, "attemptCount": 0, "completedAt": null, "documentId": "11111111-1111-4111-8111-111111111111", "entitlement": { "capturedAt": "2026-07-20T12:08:00.000Z", "catalogVersion": "2026-07-20.1", "plan": "free", "source": "free_trial", "units": 0 }, "error": null, "id": "99999999-9999-4999-8999-999999999999", "outputFormat": "pdf", "provenance": { "assetSetSha256": null, "catalogSha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "catalogVersion": "2026-07-20.1", "channel": "rest_v2", "engineVersion": "1.0.1", "fontSetSha256": null, "locale": "en", "manifestSha256": null, "optionsSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "renderOptionsSha256": null, "rendererReleaseChecksum": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "rendererVersion": "gotenberg-8.34.0", "requestSha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "sourceSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "synthetic": false, "templateDefinitionSha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "templateId": "executive", "templateReleaseId": "44444444-4444-4444-8444-444444444444", "templateReleaseSha256": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" }, "purpose": "preview", "queuedAt": "2026-07-20T12:08:01.000Z", "requestSha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "retention": { "deleteRequestedAt": null, "deletedAt": null, "expiresAt": "2026-07-20T12:23:00.000Z", "policy": "managed_default" }, "revisionId": "22222222-2222-4222-8222-222222222222", "startedAt": null, "status": "queued" }, "links": { "cancel": "/api/v2/jobs/99999999-9999-4999-8999-999999999999/cancel", "self": "/api/v2/jobs/99999999-9999-4999-8999-999999999999" }, "warnings": [] } }, "PublishRequest": { "value": { "output": { "filename": "northstar-launch-brief.pdf", "format": "pdf" }, "revisionId": "22222222-2222-4222-8222-222222222222" } }, "QuotaError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "entitlement", "code": "quota_exhausted", "httpStatus": 402, "message": "No final publication units remain for this entitlement.", "retryable": false } } }, "RateLimitedError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "entitlement", "code": "rate_limited", "details": { "retryAfterSeconds": 30 }, "httpStatus": 429, "message": "Too many publishing requests. Retry after 30 seconds.", "retryable": true } } }, "RevisionCreated": { "value": { "contractVersion": "publishing.lifecycle.v1", "documentId": "11111111-1111-4111-8111-111111111111", "links": { "document": "/api/v2/documents/11111111-1111-4111-8111-111111111111", "preview": "/api/v2/documents/11111111-1111-4111-8111-111111111111/previews", "publish": "/api/v2/documents/11111111-1111-4111-8111-111111111111/publishes" }, "revision": { "createdAt": "2026-07-20T12:05:00.000Z", "documentId": "11111111-1111-4111-8111-111111111111", "id": "88888888-8888-4888-8888-888888888888", "parentRevisionId": "22222222-2222-4222-8222-222222222222", "sequence": 2, "sourceBytes": 96, "sourceSha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "specSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } } }, "ServiceUnavailableError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "internal", "code": "service_unavailable", "details": { "retryAfterSeconds": 30 }, "httpStatus": 503, "message": "Publishing is temporarily unavailable.", "retryable": true } } }, "UnauthorizedError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "authentication", "code": "unauthorized", "httpStatus": 401, "message": "A valid API key is required.", "retryable": false } } }, "UnsupportedMediaTypeError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "input", "code": "invalid_request", "httpStatus": 415, "message": "Content-Type must be application/json.", "retryable": false } } }, "UnprocessableContentError": { "value": { "contractVersion": "publishing.lifecycle.v1", "error": { "category": "input", "code": "invalid_request", "httpStatus": 422, "message": "The document source or publication options are invalid.", "retryable": false } } }, "WebhookCreated": { "value": { "contractVersion": "publishing.lifecycle.v1", "secret": { "createdAt": "2026-07-20T15:00:00.000Z", "fingerprint": "8f4e2b731d0c9a65", "signingSecret": "whsec_exampleSigningSecretForDocumentationOnly_123456", "version": 1 }, "subscription": { "createdAt": "2026-07-20T15:00:00.000Z", "currentSecretFingerprint": "8f4e2b731d0c9a65", "currentSecretVersion": 1, "description": "Production publishing events", "disabledAt": null, "endpoint": "https://hooks.example.com/markdowntopdf", "eventTypes": [ "job.succeeded", "job.failed", "job.cancelled" ], "id": "55555555-5555-4555-8555-555555555555", "status": "active", "updatedAt": "2026-07-20T15:00:00.000Z" } } }, "WebhookDelivery": { "value": { "apiVersion": "2026-07-20", "createdAt": "2026-07-20T15:30:01.000Z", "data": { "artifact": { "bytes": 984747, "contentType": "application/pdf", "expiresAt": "2026-07-27T15:30:00.000Z", "filename": "northstar-launch-brief.pdf", "format": "pdf", "id": "44444444-4444-4444-8444-444444444444", "pageCount": 3, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "job": { "completedAt": "2026-07-20T15:30:00.000Z", "createdAt": "2026-07-20T15:29:00.000Z", "documentId": "11111111-1111-4111-8111-111111111111", "error": null, "id": "33333333-3333-4333-8333-333333333333", "output": { "filename": "northstar-launch-brief.pdf", "format": "pdf" }, "purpose": "final", "revisionId": "22222222-2222-4222-8222-222222222222", "status": "succeeded" } }, "id": "66666666-6666-4666-8666-666666666666", "type": "job.succeeded" } }, "WebhookDisabled": { "value": { "contractVersion": "publishing.lifecycle.v1", "subscription": { "createdAt": "2026-07-20T15:00:00.000Z", "currentSecretFingerprint": "9a7c1e204f63d8b2", "currentSecretVersion": 2, "description": "Production publishing events", "disabledAt": "2026-07-20T15:20:00.000Z", "endpoint": "https://hooks.example.com/markdowntopdf", "eventTypes": [ "job.succeeded", "job.failed", "job.cancelled" ], "id": "55555555-5555-4555-8555-555555555555", "status": "disabled", "updatedAt": "2026-07-20T15:20:00.000Z" } } }, "WebhookList": { "value": { "contractVersion": "publishing.lifecycle.v1", "subscriptions": [ { "createdAt": "2026-07-20T15:00:00.000Z", "currentSecretFingerprint": "8f4e2b731d0c9a65", "currentSecretVersion": 1, "description": "Production publishing events", "disabledAt": null, "endpoint": "https://hooks.example.com/markdowntopdf", "eventTypes": [ "job.succeeded", "job.failed", "job.cancelled" ], "id": "55555555-5555-4555-8555-555555555555", "status": "active", "updatedAt": "2026-07-20T15:00:00.000Z" } ] } }, "WebhookRotated": { "value": { "contractVersion": "publishing.lifecycle.v1", "secret": { "createdAt": "2026-07-20T15:10:00.000Z", "fingerprint": "9a7c1e204f63d8b2", "signingSecret": "whsec_rotatedSigningSecretForDocumentation_1234567", "version": 2 }, "subscriptionId": "55555555-5555-4555-8555-555555555555" } } }, "headers": { "CorrelationId": { "description": "Content-free support correlation identifier. Safe to include in a support request.", "schema": { "format": "uuid", "type": "string" } }, "IdempotencyReplayed": { "description": "True when the response replays the original result for this principal, operation, key, and canonical request hash.", "schema": { "type": "boolean" } }, "RetryAfter": { "description": "Minimum delay before retrying, represented as seconds or an HTTP date.", "schema": { "type": "string" } } }, "parameters": { "ArtifactId": { "description": "Owner-scoped artifact identifier.", "in": "path", "name": "artifactId", "required": true, "schema": { "format": "uuid", "type": "string" } }, "Cursor": { "description": "Opaque cursor returned by the preceding page. Do not inspect or construct it.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } }, "DocumentId": { "description": "Owner-scoped managed document identifier.", "in": "path", "name": "documentId", "required": true, "schema": { "format": "uuid", "type": "string" } }, "IdempotencyKey": { "description": "Required for replay-safe mutations. Use a unique opaque value for one logical operation and reuse it only with an identical request.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 200, "minLength": 8, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "type": "string" } }, "JobId": { "description": "Owner-scoped publishing job identifier.", "in": "path", "name": "jobId", "required": true, "schema": { "format": "uuid", "type": "string" } }, "Limit": { "description": "Maximum number of documents to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, "WebhookId": { "description": "Owner-scoped outbound webhook subscription identifier.", "in": "path", "name": "webhookId", "required": true, "schema": { "format": "uuid", "type": "string" } } }, "responses": { "Conflict": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/ConflictError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The resource state conflicts with the request, including idempotency-key reuse with a different canonical request hash.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Forbidden": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/ForbiddenError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The principal is authenticated but lacks the operation's required scope.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "InvalidRequest": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/InvalidRequestError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The JSON body, path, query, or required idempotency header is invalid.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "NotFound": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/NotFoundError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The resource does not exist or is not visible to this principal. Cross-tenant misses use the same response.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "QuotaExhausted": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/QuotaError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The final-publish entitlement is exhausted. Previews never return this response for publication-unit usage.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "RateLimited": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/RateLimitedError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The request is temporarily rate limited. No final publication unit is consumed.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "ServiceUnavailable": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/ServiceUnavailableError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "A transient publishing, queue, renderer, or storage dependency is unavailable. No failed render consumes a final publication unit.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "Unauthorized": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/UnauthorizedError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The bearer credential is missing, malformed, expired, revoked, or belongs to the wrong environment.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "UnsupportedMediaType": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/UnsupportedMediaTypeError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The request body is not application/json.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "UnprocessableContent": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/UnprocessableContentError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The body is valid JSON but its document source, template, locale, or output configuration cannot be accepted.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } } }, "schemas": { "CreateWebhookRequest": { "additionalProperties": false, "properties": { "description": { "maxLength": 160, "minLength": 1, "type": [ "string", "null" ] }, "endpoint": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" }, "eventTypes": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "maxItems": 3, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "endpoint", "eventTypes" ], "type": "object" }, "ArtifactLinkResponse": { "additionalProperties": false, "properties": { "artifactId": { "format": "uuid", "type": "string" }, "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "href": { "format": "uri", "type": "string" }, "retention": { "$ref": "#/components/schemas/Retention" } }, "required": [ "artifactId", "contractVersion", "expiresAt", "href", "retention" ], "type": "object" }, "ArtifactSummary": { "additionalProperties": false, "properties": { "bytes": { "minimum": 1, "type": "integer" }, "contentType": { "const": "application/pdf", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "downloadPath": { "pattern": "^/api/v2/artifacts/[0-9a-f-]+/download$", "type": "string" }, "filename": { "maxLength": 200, "minLength": 1, "type": "string" }, "finalizedAt": { "format": "date-time", "type": "string" }, "format": { "const": "pdf", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "jobId": { "format": "uuid", "type": "string" }, "pageCount": { "minimum": 1, "type": "integer" }, "retention": { "$ref": "#/components/schemas/Retention" }, "revisionId": { "format": "uuid", "type": [ "string", "null" ] }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "status": { "enum": [ "available", "expired", "deleting", "deleted" ], "type": "string" } }, "required": [ "bytes", "contentType", "createdAt", "downloadPath", "filename", "finalizedAt", "format", "id", "jobId", "pageCount", "retention", "revisionId", "sha256", "status" ], "type": "object" }, "CreateDocumentRequest": { "additionalProperties": false, "properties": { "revision": { "$ref": "#/components/schemas/CreateRevisionRequest" }, "taskId": { "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9._-]*$", "type": "string" }, "title": { "maxLength": 160, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "revision", "taskId", "title" ], "type": "object" }, "CreatePreviewRequest": { "additionalProperties": false, "properties": { "output": { "additionalProperties": false, "properties": { "filename": { "maxLength": 200, "minLength": 1, "type": "string" }, "format": { "const": "pdf", "type": "string" } }, "required": [ "filename", "format" ], "type": "object" }, "revisionId": { "format": "uuid", "type": "string" } }, "required": [ "output", "revisionId" ], "type": "object" }, "CreatePublicationRequest": { "additionalProperties": false, "properties": { "output": { "additionalProperties": false, "properties": { "filename": { "maxLength": 200, "minLength": 1, "type": "string" }, "format": { "const": "pdf", "type": "string" } }, "required": [ "filename", "format" ], "type": "object" }, "revisionId": { "format": "uuid", "type": "string" } }, "required": [ "output", "revisionId" ], "type": "object" }, "CreateRevisionRequest": { "additionalProperties": false, "properties": { "markdown": { "maxLength": 200000, "minLength": 1, "type": "string" }, "parentRevisionId": { "format": "uuid", "type": [ "string", "null" ] }, "spec": { "additionalProperties": false, "properties": { "locale": { "enum": [ "en", "es", "fr", "de", "ja", "zh-CN", "ko", "pt-BR", "ar", "ru", "hi", "it" ], "type": "string" }, "options": { "additionalProperties": false, "default": {}, "properties": { "bodyTextColor": { "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "headingTextColor": { "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "pageNumbers": { "type": "boolean" } }, "type": "object" }, "templateId": { "enum": [ "clean", "executive", "resume", "resume-ats", "resume-executive", "resume-technical", "resume-product", "resume-consulting", "resume-finance", "resume-clinical", "resume-academic", "resume-graduate", "coverletter", "coverletter-ats", "coverletter-executive", "coverletter-technical", "coverletter-product", "coverletter-consulting", "coverletter-finance", "coverletter-clinical", "coverletter-academic", "coverletter-graduate", "assignment-high-school-essay", "assignment-high-school-lab", "assignment-high-school-project", "assignment-college-essay", "assignment-college-case-study", "assignment-college-lab", "assignment-university-research", "assignment-university-capstone", "assignment-university-problem-set", "proposal-consulting", "proposal-project", "proposal-sales", "proposal-grant", "proposal-sponsorship", "proposal-rfp-response", "proposal-freelance", "proposal-partnership", "proposal-nonprofit-program", "marketing-product-one-pager", "marketing-customer-case-study", "marketing-white-paper", "marketing-company-profile", "marketing-media-kit", "marketing-press-kit", "marketing-product-brochure", "marketing-campaign-report", "marketing-event-program", "academic", "academic-submission", "academic-proceedings", "book-literary", "book-editorial", "book-guide", "legal", "creative" ], "type": "string", "x-publication-catalog-version": "2026-07-20.1" } }, "required": [ "locale", "options", "templateId" ], "type": "object" } }, "required": [ "markdown", "parentRevisionId", "spec" ], "type": "object" }, "DeletionResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "documentId": { "format": "uuid", "type": "string" }, "retention": { "$ref": "#/components/schemas/Retention" }, "status": { "enum": [ "accepted", "already_deleting", "already_deleted" ], "type": "string" } }, "required": [ "contractVersion", "documentId", "retention", "status" ], "type": "object" }, "Document": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "lastActivityAt": { "format": "date-time", "type": "string" }, "latestRevisionId": { "format": "uuid", "type": [ "string", "null" ] }, "locale": { "enum": [ "en", "es", "fr", "de", "ja", "zh-CN", "ko", "pt-BR", "ar", "ru", "hi", "it" ], "type": "string" }, "retention": { "$ref": "#/components/schemas/Retention" }, "status": { "enum": [ "active", "deleting", "deleted" ], "type": "string" }, "taskId": { "maxLength": 100, "minLength": 1, "type": "string" }, "title": { "maxLength": 160, "minLength": 1, "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "createdAt", "id", "lastActivityAt", "latestRevisionId", "locale", "retention", "status", "taskId", "title", "updatedAt" ], "type": "object" }, "DocumentDetailResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" }, "latestRevision": { "anyOf": [ { "$ref": "#/components/schemas/Revision" }, { "type": "null" } ] }, "links": { "$ref": "#/components/schemas/DocumentLinks" } }, "required": [ "contractVersion", "document", "latestRevision", "links" ], "type": "object" }, "DocumentLinks": { "additionalProperties": false, "properties": { "preview": { "pattern": "^/api/v2/documents/", "type": "string" }, "publish": { "pattern": "^/api/v2/documents/", "type": "string" }, "revisions": { "pattern": "^/api/v2/documents/", "type": "string" }, "self": { "pattern": "^/api/v2/documents/", "type": "string" } }, "required": [ "preview", "publish", "revisions", "self" ], "type": "object" }, "DocumentListResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "documents": { "items": { "$ref": "#/components/schemas/Document" }, "maxItems": 100, "type": "array" }, "pagination": { "additionalProperties": false, "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "maxLength": 512, "type": [ "string", "null" ] } }, "required": [ "hasMore", "nextCursor" ], "type": "object" } }, "required": [ "contractVersion", "documents", "pagination" ], "type": "object" }, "DocumentResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" }, "links": { "$ref": "#/components/schemas/DocumentLinks" }, "revision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "contractVersion", "document", "links", "revision" ], "type": "object" }, "EntitlementSnapshot": { "additionalProperties": false, "properties": { "capturedAt": { "format": "date-time", "type": "string" }, "catalogVersion": { "type": "string" }, "plan": { "enum": [ "free", "monthly", "yearly", "credits", "admin" ], "type": "string" }, "source": { "enum": [ "free_trial", "web_daily", "api_monthly", "credit_pack", "subscription", "admin" ], "type": "string" }, "units": { "maximum": 100, "minimum": 0, "type": "integer" } }, "required": [ "capturedAt", "catalogVersion", "plan", "source", "units" ], "type": "object" }, "Job": { "additionalProperties": false, "properties": { "acceptedAt": { "format": "date-time", "type": "string" }, "artifactId": { "format": "uuid", "type": [ "string", "null" ] }, "attemptCount": { "maximum": 100, "minimum": 0, "type": "integer" }, "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "documentId": { "format": "uuid", "type": [ "string", "null" ] }, "entitlement": { "$ref": "#/components/schemas/EntitlementSnapshot" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/PublishingError" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "outputFormat": { "const": "pdf", "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "purpose": { "enum": [ "preview", "final" ], "type": "string" }, "queuedAt": { "format": "date-time", "type": [ "string", "null" ] }, "requestSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "retention": { "$ref": "#/components/schemas/Retention" }, "revisionId": { "format": "uuid", "type": [ "string", "null" ] }, "startedAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "accepted", "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "acceptedAt", "artifactId", "attemptCount", "completedAt", "documentId", "entitlement", "error", "id", "outputFormat", "provenance", "purpose", "queuedAt", "requestSha256", "retention", "revisionId", "startedAt", "status" ], "type": "object" }, "JobResponse": { "additionalProperties": false, "properties": { "artifact": { "anyOf": [ { "$ref": "#/components/schemas/ArtifactSummary" }, { "type": "null" } ] }, "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "job": { "$ref": "#/components/schemas/Job" }, "links": { "additionalProperties": false, "properties": { "cancel": { "pattern": "^/api/v2/jobs/", "type": "string" }, "self": { "pattern": "^/api/v2/jobs/", "type": "string" } }, "required": [ "cancel", "self" ], "type": "object" }, "warnings": { "items": { "$ref": "#/components/schemas/Warning" }, "maxItems": 100, "type": "array" } }, "required": [ "artifact", "contractVersion", "job", "links", "warnings" ], "type": "object" }, "Provenance": { "additionalProperties": false, "properties": { "assetSetSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "catalogSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "catalogVersion": { "type": "string" }, "channel": { "enum": [ "web", "rest_v1", "rest_v2", "mcp_v1", "mcp_v2", "cli", "github_action", "internal" ], "type": "string" }, "engineVersion": { "type": [ "string", "null" ] }, "fontSetSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "locale": { "enum": [ "en", "es", "fr", "de", "ja", "zh-CN", "ko", "pt-BR", "ar", "ru", "hi", "it" ], "type": "string" }, "manifestSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "optionsSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "renderOptionsSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "rendererReleaseChecksum": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "rendererVersion": { "type": "string" }, "requestSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "sourceSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "synthetic": { "type": "boolean" }, "templateDefinitionSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "templateId": { "enum": [ "clean", "executive", "resume", "resume-ats", "resume-executive", "resume-technical", "resume-product", "resume-consulting", "resume-finance", "resume-clinical", "resume-academic", "resume-graduate", "coverletter", "coverletter-ats", "coverletter-executive", "coverletter-technical", "coverletter-product", "coverletter-consulting", "coverletter-finance", "coverletter-clinical", "coverletter-academic", "coverletter-graduate", "assignment-high-school-essay", "assignment-high-school-lab", "assignment-high-school-project", "assignment-college-essay", "assignment-college-case-study", "assignment-college-lab", "assignment-university-research", "assignment-university-capstone", "assignment-university-problem-set", "proposal-consulting", "proposal-project", "proposal-sales", "proposal-grant", "proposal-sponsorship", "proposal-rfp-response", "proposal-freelance", "proposal-partnership", "proposal-nonprofit-program", "marketing-product-one-pager", "marketing-customer-case-study", "marketing-white-paper", "marketing-company-profile", "marketing-media-kit", "marketing-press-kit", "marketing-product-brochure", "marketing-campaign-report", "marketing-event-program", "academic", "academic-submission", "academic-proceedings", "book-literary", "book-editorial", "book-guide", "legal", "creative" ], "type": "string" }, "templateReleaseId": { "format": "uuid", "type": [ "string", "null" ] }, "templateReleaseSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" } }, "required": [ "assetSetSha256", "catalogSha256", "catalogVersion", "channel", "engineVersion", "fontSetSha256", "locale", "manifestSha256", "optionsSha256", "renderOptionsSha256", "rendererReleaseChecksum", "rendererVersion", "requestSha256", "sourceSha256", "synthetic", "templateDefinitionSha256", "templateId", "templateReleaseId", "templateReleaseSha256" ], "type": "object" }, "PublishingError": { "additionalProperties": false, "properties": { "category": { "enum": [ "input", "authentication", "authorization", "entitlement", "conflict", "render", "storage", "delivery", "internal" ], "type": "string" }, "code": { "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "idempotency_conflict", "quota_exhausted", "reservation_conflict", "invalid_state_transition", "rendering_failed", "artifact_unavailable", "artifact_expired", "job_cancelled", "rate_limited", "service_unavailable", "internal_error" ], "type": "string" }, "details": { "additionalProperties": false, "properties": { "correlationId": { "format": "uuid", "type": "string" }, "currentState": { "maxLength": 40, "minLength": 1, "type": "string" }, "expectedStates": { "items": { "maxLength": 40, "minLength": 1, "type": "string" }, "maxItems": 10, "type": "array" }, "field": { "maxLength": 100, "minLength": 1, "type": "string" }, "retryAfterSeconds": { "maximum": 86400, "minimum": 0, "type": "integer" } }, "type": "object" }, "httpStatus": { "maximum": 599, "minimum": 400, "type": "integer" }, "message": { "maxLength": 300, "minLength": 1, "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "category", "code", "httpStatus", "message", "retryable" ], "type": "object" }, "PublishingErrorEnvelope": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "error": { "$ref": "#/components/schemas/PublishingError" } }, "required": [ "contractVersion", "error" ], "type": "object" }, "Retention": { "additionalProperties": false, "properties": { "deleteRequestedAt": { "format": "date-time", "type": [ "string", "null" ] }, "deletedAt": { "format": "date-time", "type": [ "string", "null" ] }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "policy": { "enum": [ "legacy_ephemeral", "intent_replay", "managed_default", "preview" ], "type": "string" } }, "required": [ "deleteRequestedAt", "deletedAt", "expiresAt", "policy" ], "type": "object" }, "Revision": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "documentId": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "parentRevisionId": { "format": "uuid", "type": [ "string", "null" ] }, "sequence": { "minimum": 1, "type": "integer" }, "sourceBytes": { "maximum": 2000000, "minimum": 1, "type": "integer" }, "sourceSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "specSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" } }, "required": [ "createdAt", "documentId", "id", "parentRevisionId", "sequence", "sourceBytes", "sourceSha256", "specSha256" ], "type": "object" }, "RevisionResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "documentId": { "format": "uuid", "type": "string" }, "links": { "additionalProperties": false, "properties": { "document": { "pattern": "^/api/v2/documents/", "type": "string" }, "preview": { "pattern": "^/api/v2/documents/", "type": "string" }, "publish": { "pattern": "^/api/v2/documents/", "type": "string" } }, "required": [ "document", "preview", "publish" ], "type": "object" }, "revision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "contractVersion", "documentId", "links", "revision" ], "type": "object" }, "Warning": { "additionalProperties": false, "properties": { "code": { "enum": [ "font_substituted", "image_omitted", "image_scaled", "page_break_adjusted", "table_scaled", "unsupported_markdown" ], "type": "string" }, "message": { "maxLength": 300, "minLength": 1, "type": "string" }, "path": { "maxLength": 160, "minLength": 1, "type": [ "string", "null" ] }, "severity": { "enum": [ "info", "warning" ], "type": "string" } }, "required": [ "code", "message", "path", "severity" ], "type": "object" }, "WebhookDeliveryArtifact": { "additionalProperties": false, "properties": { "bytes": { "minimum": 1, "type": "integer" }, "contentType": { "const": "application/pdf", "type": "string" }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "filename": { "maxLength": 200, "minLength": 1, "type": "string" }, "format": { "const": "pdf", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "pageCount": { "minimum": 1, "type": "integer" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" } }, "required": [ "bytes", "contentType", "expiresAt", "filename", "format", "id", "pageCount", "sha256" ], "type": "object" }, "WebhookDeliveryError": { "additionalProperties": false, "properties": { "category": { "maxLength": 100, "type": [ "string", "null" ] }, "code": { "maxLength": 100, "type": [ "string", "null" ] }, "httpStatus": { "maximum": 599, "minimum": 100, "type": [ "integer", "null" ] }, "retryable": { "type": [ "boolean", "null" ] } }, "required": [ "category", "code", "httpStatus", "retryable" ], "type": "object" }, "WebhookDeliveryJob": { "additionalProperties": false, "properties": { "completedAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "documentId": { "format": "uuid", "type": "string" }, "error": { "oneOf": [ { "$ref": "#/components/schemas/WebhookDeliveryError" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "output": { "additionalProperties": false, "properties": { "filename": { "maxLength": 200, "minLength": 1, "type": "string" }, "format": { "const": "pdf", "type": "string" } }, "required": [ "filename", "format" ], "type": "object" }, "purpose": { "enum": [ "preview", "final" ], "type": "string" }, "revisionId": { "format": "uuid", "type": "string" }, "status": { "enum": [ "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "completedAt", "createdAt", "documentId", "error", "id", "output", "purpose", "revisionId", "status" ], "type": "object" }, "WebhookDeliveryPayload": { "additionalProperties": false, "properties": { "apiVersion": { "const": "2026-07-20", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "data": { "additionalProperties": false, "properties": { "artifact": { "oneOf": [ { "$ref": "#/components/schemas/WebhookDeliveryArtifact" }, { "type": "null" } ] }, "job": { "$ref": "#/components/schemas/WebhookDeliveryJob" } }, "required": [ "artifact", "job" ], "type": "object" }, "id": { "format": "uuid", "type": "string" }, "type": { "$ref": "#/components/schemas/WebhookEventType" } }, "required": [ "apiVersion", "createdAt", "data", "id", "type" ], "type": "object" }, "WebhookEventType": { "enum": [ "job.succeeded", "job.failed", "job.cancelled" ], "type": "string" }, "WebhookListResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "subscriptions": { "items": { "$ref": "#/components/schemas/WebhookSubscription" }, "maxItems": 100, "type": "array" } }, "required": [ "contractVersion", "subscriptions" ], "type": "object" }, "WebhookResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "secret": { "$ref": "#/components/schemas/WebhookSecret" }, "subscription": { "$ref": "#/components/schemas/WebhookSubscription" } }, "required": [ "contractVersion", "subscription" ], "type": "object" }, "WebhookRotationResponse": { "additionalProperties": false, "properties": { "contractVersion": { "const": "publishing.lifecycle.v1", "type": "string" }, "secret": { "$ref": "#/components/schemas/WebhookSecret" }, "subscriptionId": { "format": "uuid", "type": "string" } }, "required": [ "contractVersion", "secret", "subscriptionId" ], "type": "object" }, "WebhookSecret": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "fingerprint": { "pattern": "^[a-f0-9]{16}$", "type": "string" }, "signingSecret": { "pattern": "^whsec_[A-Za-z0-9_-]{40,100}$", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "createdAt", "fingerprint", "signingSecret", "version" ], "type": "object" }, "WebhookSubscription": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "currentSecretFingerprint": { "pattern": "^[a-f0-9]{16}$", "type": "string" }, "currentSecretVersion": { "minimum": 1, "type": "integer" }, "description": { "maxLength": 160, "minLength": 1, "type": [ "string", "null" ] }, "disabledAt": { "format": "date-time", "type": [ "string", "null" ] }, "endpoint": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" }, "eventTypes": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "maxItems": 3, "minItems": 1, "type": "array", "uniqueItems": true }, "id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "createdAt", "currentSecretFingerprint", "currentSecretVersion", "description", "disabledAt", "endpoint", "eventTypes", "id", "status", "updatedAt" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "mp_live_ or mp_test_ API key", "description": "Environment-bound product API key provisioned for the private beta. Every route enforces its declared lifecycle scopes.", "scheme": "bearer", "type": "http", "x-supported-scopes": [ "documents.preview", "documents.render", "documents.read", "documents.delete", "templates.read", "webhooks.read", "webhooks.write" ] } } }, "externalDocs": { "description": "v1 to v2 migration and compatibility guide", "url": "https://markdowntopdfconverter.com/api-v2-migration.md" }, "info": { "description": "Active private-beta managed-publishing API for immutable revisions, preview and final jobs, private artifacts, expiry, and deletion. Provisioned clients may use v2 in production; /api/v1/convert remains supported.", "title": "Markdown to PDF Converter Publishing API v2", "version": "2.0.0", "x-lifecycle-contract-version": "publishing.lifecycle.v1", "x-publication-catalog-sha256": "062f47e967d594779cf28cfd7d825de5e538d3206fe328330b9ef0e5e408d14b", "x-publication-catalog-version": "2026-07-20.1", "x-release-status": "private-beta", "x-v1-openapi": "https://markdowntopdfconverter.com/openapi.json" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "openapi": "3.1.0", "paths": { "/api/v2/artifacts/{artifactId}/download": { "get": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "naturally_safe", "replayHeader": null }, "x-required-scopes": [ "documents.read" ], "x-retention": { "contract": "The redirect URL lasts at most five minutes; the underlying artifact retains its own expiresAt and may be deleted earlier.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Retry transport failures, 429, and 503 with exponential backoff and full jitter. Honor Retry-After.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Authorize ownership and redirect to a private, short-lived download URL. Redirect targets are never persisted or returned in logs.", "operationId": "downloadPublishingArtifact", "parameters": [ { "$ref": "#/components/parameters/ArtifactId" } ], "responses": { "302": { "description": "Redirect to the authorized private artifact.", "headers": { "Cache-Control": { "schema": { "const": "private, no-store, max-age=0", "type": "string" } }, "Location": { "description": "Short-lived private storage URL.", "required": true, "schema": { "format": "uri", "type": "string" } }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/GoneError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The artifact has expired or was deleted.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Download an artifact", "tags": [ "Artifacts" ] } }, "/api/v2/artifacts/{artifactId}/links": { "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "non_persisting", "replayHeader": null }, "x-required-scopes": [ "documents.read" ], "x-retention": { "contract": "The returned URL lasts at most five minutes and does not extend the artifact's expiresAt.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "This operation does not persist or charge. A retry may return a different short-lived URL for the same artifact.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Mint a private download URL after both tenant visibility and explicit owner checks. The URL is never stored.", "operationId": "createPublishingArtifactLink", "parameters": [ { "$ref": "#/components/parameters/ArtifactId" } ], "responses": { "201": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/ArtifactLink" } }, "schema": { "$ref": "#/components/schemas/ArtifactLinkResponse" } } }, "description": "A new short-lived download link.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Cache-Control": { "schema": { "const": "private, no-store" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/GoneError" } }, "schema": { "$ref": "#/components/schemas/PublishingErrorEnvelope" } } }, "description": "The artifact has expired or was deleted." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Create a short-lived artifact link", "tags": [ "Artifacts" ] } }, "/api/v2/documents": { "get": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "naturally_safe", "replayHeader": null }, "x-required-scopes": [ "documents.read" ], "x-retention": { "contract": "Each document includes its content expiry. Opaque cursors contain no document content and expire with list-state retention.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Retry transport failures, 429, and 503 with exponential backoff and full jitter. Honor Retry-After.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "List only documents owned by the API-key principal, ordered by latest activity.", "operationId": "listPublishingDocuments", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/DocumentList" } }, "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } }, "description": "An owner-scoped page of documents.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "List managed documents", "tags": [ "Documents" ] }, "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "documents.render" ], "x-retention": { "contract": "The encrypted source and immutable revision expire 30 days after document activity unless the owner deletes them first.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Create an owner-scoped managed document and its first immutable revision. This does not render or consume a final publication unit.", "operationId": "createPublishingDocument", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/CreateDocumentRequest" } }, "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/DocumentCreated" } }, "schema": { "$ref": "#/components/schemas/DocumentResponse" } } }, "description": "The document and first immutable revision. A same-key replay returns the identical resource identities.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExhausted" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Create a managed document", "tags": [ "Documents" ] } }, "/api/v2/documents/{documentId}": { "delete": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "resource_idempotent", "replayHeader": null }, "x-required-scopes": [ "documents.delete" ], "x-retention": { "contract": "Deletion tombstones immediately, cancels active work, deletes private objects first, and then redacts content metadata under the retention sweeper.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Repeat DELETE for the same document ID. already_deleting and already_deleted are successful idempotent outcomes.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Request deletion of the document, all immutable sources, previews, final artifacts, and active lifecycle work.", "operationId": "deletePublishingDocument", "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/DeletionAccepted" } }, "schema": { "$ref": "#/components/schemas/DeletionResponse" } } }, "description": "Deletion was already in progress or complete.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "202": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/DeletionAccepted" } }, "schema": { "$ref": "#/components/schemas/DeletionResponse" } } }, "description": "Deletion was accepted and object-first cleanup is pending.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Delete a managed document", "tags": [ "Documents" ] }, "get": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "naturally_safe", "replayHeader": null }, "x-required-scopes": [ "documents.read" ], "x-retention": { "contract": "The response states source/document expiry. Deleted and cross-tenant documents resolve as not found.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Retry transport failures, 429, and 503 with exponential backoff and full jitter. Honor Retry-After.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Retrieve an owner-scoped document and its latest immutable revision summary.", "operationId": "getPublishingDocument", "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/DocumentDetail" } }, "schema": { "$ref": "#/components/schemas/DocumentDetailResponse" } } }, "description": "The managed document and latest revision summary.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Get a managed document", "tags": [ "Documents" ] } }, "/api/v2/documents/{documentId}/previews": { "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "documents.preview" ], "x-retention": { "contract": "Preview source follows the document's 30-day window; preview artifacts expire after 15 minutes and never become final artifacts in place.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Create a private PDF preview. Previews are separately rate limited and never consume trial, subscription, API-call, or credit-pack publication units.", "operationId": "createPublishingPreview", "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/PreviewRequest" } }, "schema": { "$ref": "#/components/schemas/CreatePreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/PreviewJobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "A preview completed within the synchronous threshold.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "202": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/PreviewJobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "The preview was accepted for asynchronous processing.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Create a document preview", "tags": [ "Publishing" ] } }, "/api/v2/documents/{documentId}/publishes": { "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "documents.render" ], "x-retention": { "contract": "Final artifacts expire seven days after finalization; source follows the document's 30-day activity window. A final unit commits only after successful finalization.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Create a final publication job from an immutable revision. Admission reserves the disclosed unit; failure or cancellation releases it.", "operationId": "publishDocumentRevision", "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/PublishRequest" } }, "schema": { "$ref": "#/components/schemas/CreatePublicationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/JobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "The publication completed within the synchronous threshold.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "202": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/JobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "The final publication was accepted for asynchronous processing.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExhausted" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Publish an immutable revision", "tags": [ "Publishing" ] } }, "/api/v2/documents/{documentId}/revisions": { "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "documents.render" ], "x-retention": { "contract": "Encrypted source revisions expire 30 days after document activity unless owner deletion occurs first. Safe hashes and tombstones follow the operational metadata policy.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Append an immutable source and publication-spec revision. The parent must belong to the same document and cannot be changed after creation.", "operationId": "createPublishingRevision", "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/CreateRevisionRequest" } }, "schema": { "$ref": "#/components/schemas/CreateRevisionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/RevisionCreated" } }, "schema": { "$ref": "#/components/schemas/RevisionResponse" } } }, "description": "The immutable revision and lifecycle links.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExhausted" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Create an immutable revision", "tags": [ "Documents" ] } }, "/api/v2/jobs/{jobId}": { "get": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "naturally_safe", "replayHeader": null }, "x-required-scopes": [ "documents.read" ], "x-retention": { "contract": "Job and typed failure detail expires after 30 days. Artifact and source expiry remain explicit in their own retention objects.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Retry transport failures, 429, and 503 with exponential backoff and full jitter. Honor Retry-After.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Poll an owner-scoped preview or final job. Terminal states never transition again.", "operationId": "getPublishingJob", "parameters": [ { "$ref": "#/components/parameters/JobId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/JobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "Current job, warnings, optional artifact, and lifecycle links.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Get a publishing job", "tags": [ "Jobs" ] } }, "/api/v2/jobs/{jobId}/cancel": { "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "documents.render" ], "x-retention": { "contract": "Cancellation releases an uncommitted final reservation and leaves safe job metadata for 30 days. Existing artifacts are unaffected and remain deletable through the document.", "responseField": "retention" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Cancel accepted, queued, or running work. Repeating a successful cancellation returns the same terminal job without a second effect.", "operationId": "cancelPublishingJob", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/JobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "The job is already cancelled or terminal.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "202": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/JobAccepted" } }, "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "Cancellation was accepted; a leased worker is being fenced or drained.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExhausted" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Cancel a publishing job", "tags": [ "Jobs" ] } }, "/api/v2/webhooks": { "get": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "naturally_safe", "replayHeader": null }, "x-required-scopes": [ "webhooks.read" ], "x-retention": { "contract": "Subscriptions remain visible until account deletion; disabledAt records permanent shutdown without exposing signing material.", "responseField": "subscriptions[].disabledAt" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Retry transport failures, 429, and 503 with exponential backoff and full jitter. Honor Retry-After.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "List owner-scoped webhook subscriptions. Signing secrets are never included in list responses.", "operationId": "listPublishingWebhooks", "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/WebhookList" } }, "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } }, "description": "The owner's webhook subscriptions, including status and signing-secret fingerprints.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "List webhook subscriptions", "tags": [ "Webhooks" ] }, "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "webhooks.write" ], "x-retention": { "contract": "The encrypted signing secret and subscription remain until account deletion. Plaintext is returned only by the idempotent create response.", "responseField": "subscription.disabledAt" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Create an outbound terminal-job subscription. The endpoint must resolve exclusively to public addresses. Store the returned signing secret securely; list responses expose only its fingerprint.", "operationId": "createPublishingWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/CreateWebhookRequest" } }, "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/WebhookCreated" } }, "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "The subscription and its encrypted-at-rest signing secret. A same-key replay returns the original secret.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExhausted" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableContent" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Create a webhook subscription", "tags": [ "Webhooks" ] } }, "/api/v2/webhooks/{webhookId}": { "delete": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": null, "keyHeader": null, "mode": "resource_idempotent", "replayHeader": null }, "x-required-scopes": [ "webhooks.write" ], "x-retention": { "contract": "Disablement is permanent and timestamped. Pending and leased deliveries are cancelled; already-sent requests remain subject to receiver deduplication.", "responseField": "subscription.disabledAt" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Repeat DELETE for the same subscription ID. An already-disabled subscription is a successful idempotent outcome.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Permanently disable a subscription and cancel its undelivered work. Rendering and artifact finalization are independent of this operation.", "operationId": "disablePublishingWebhook", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/WebhookDisabled" } }, "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "The disabled subscription.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Disable a webhook subscription", "tags": [ "Webhooks" ] } }, "/api/v2/webhooks/{webhookId}/rotate-secret": { "post": { "security": [ { "bearerAuth": [] } ], "x-idempotency": { "conflictStatus": 409, "keyHeader": "Idempotency-Key", "mode": "key_required", "replayHeader": "Idempotency-Replayed" }, "x-required-scopes": [ "webhooks.write" ], "x-retention": { "contract": "Retired encrypted secrets remain only for deliveries already pinned to them. The new plaintext secret is returned by the idempotent rotation response.", "responseField": "secret.createdAt" }, "x-retry": { "retryOnStatuses": [ 429, 503 ], "strategy": "Reuse the same Idempotency-Key. A replay returns the original rotated secret and never creates another version.", "usesRetryAfter": true }, "x-runtime-availability": "private-beta", "description": "Rotate the signing secret without invalidating deliveries already created under the preceding version.", "operationId": "rotatePublishingWebhookSecret", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "content": { "application/json": { "examples": { "default": { "$ref": "#/components/examples/WebhookRotated" } }, "schema": { "$ref": "#/components/schemas/WebhookRotationResponse" } } }, "description": "The newly active signing secret and subscription identifier.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Rotate a webhook signing secret", "tags": [ "Webhooks" ] } } }, "servers": [ { "description": "Production origin for provisioned private-beta v2 clients and supported v1 clients.", "url": "https://markdowntopdfconverter.com" } ], "tags": [ { "description": "Create, inspect, revise, and delete managed publications.", "name": "Documents" }, { "description": "Create previews and final publication jobs.", "name": "Publishing" }, { "description": "Poll and cancel asynchronous lifecycle work.", "name": "Jobs" }, { "description": "Mint authorized short-lived links and download artifacts.", "name": "Artifacts" }, { "description": "Subscribe to signed terminal publishing events without coupling endpoint health to rendering.", "name": "Webhooks" } ], "x-compatibility": { "deprecationNoticeDays": 90, "minimumV1ObservationDays": 180, "v1OpenApiPath": "/openapi.json", "v1Status": "supported", "v2Status": "private-beta" }, "x-webhooks": { "deliveryHeaders": { "deliveryId": "X-MD2PDF-Delivery", "eventId": "X-MD2PDF-Event", "eventType": "X-MD2PDF-Event-Type", "signature": "X-MD2PDF-Signature", "version": "X-MD2PDF-Webhook-Version" }, "deliverySemantics": "At least once. Deduplicate the same X-MD2PDF-Delivery value before applying side effects.", "endpointPolicy": "Public HTTPS hostnames on port 443 only. Redirects and private, loopback, link-local, reserved, or mixed DNS answers are rejected.", "payload": { "$ref": "#/components/schemas/WebhookDeliveryPayload" }, "retry": { "maximumAttempts": 12, "maximumDelaySeconds": 3600, "retryStatuses": [ 408, 409, 425, 429, "5xx" ], "windowSeconds": 86400 }, "signature": { "algorithm": "HMAC-SHA256", "headerFormat": "t=,v1=", "signedBytes": ".", "toleranceSeconds": 300 } } }