Markdown to PDF
5 PDFs free

API documentation

Create an immutable revision

Documents

Create an immutable revision

Append an immutable source and publication-spec revision. The parent must belong to the same document and cannot be changed after creation.

POST/api/v2/documents/{documentId}/revisions
Required scopedocuments.render

Parameters

documentId
pathstring<uuid>required

Owner-scoped managed document identifier.

Idempotency-Key
headerstringrequired

Required for replay-safe mutations. Use a unique opaque value for one logical operation and reuse it only with an identical request.

  • Minimum length: 8
  • Maximum length: 200
  • Pattern: ^[^\x00-\x1F\x7F]+$

Request body

application/jsonrequired

JSON body accepted by this operation.

CreateRevisionRequest

Create Revision Request object used by the Publishing API.

markdown
stringrequired

Markdown value.

  • Minimum length: 1
  • Maximum length: 200000
parentRevisionId
string<uuid> | nullrequired

Parent Revision Id value.

spec
objectrequired

Spec value.

Operational behavior

Idempotency

Idempotency-Key is required. Mode: key required.

Retries

Reuse the identical body and Idempotency-Key. Retry transport failures, 429, and 503 with exponential backoff and full jitter. Retry statuses: 429, 503. Honor Retry-After.

Retention

Encrypted source revisions expire 30 days after document activity unless owner deletion occurs first. Safe hashes and tombstones follow the operational metadata policy. Response field: retention.

Responses

201The immutable revision and lifecycle links.

Response headers

X-Correlation-IdIdempotency-Replayed

Response schema

RevisionResponse

Revision Response object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

documentId
string<uuid>required

Document Id value.

links
objectrequired

Links value.

revision
objectrequired

Revision value.

201 example
{
  "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"
  }
}
400The JSON body, path, query, or required idempotency header is invalid.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

400 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "input",
    "code": "invalid_request",
    "httpStatus": 400,
    "message": "The request did not match the v2 contract.",
    "retryable": false
  }
}
401The bearer credential is missing, malformed, expired, revoked, or belongs to the wrong environment.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

401 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "authentication",
    "code": "unauthorized",
    "httpStatus": 401,
    "message": "A valid API key is required.",
    "retryable": false
  }
}
402The final-publish entitlement is exhausted. Previews never return this response for publication-unit usage.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

402 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "entitlement",
    "code": "quota_exhausted",
    "httpStatus": 402,
    "message": "No final publication units remain for this entitlement.",
    "retryable": false
  }
}
403The principal is authenticated but lacks the operation's required scope.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

403 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "authorization",
    "code": "forbidden",
    "httpStatus": 403,
    "message": "The API key does not have the required scope.",
    "retryable": false
  }
}
404The resource does not exist or is not visible to this principal. Cross-tenant misses use the same response.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

404 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "authorization",
    "code": "not_found",
    "httpStatus": 404,
    "message": "The requested resource was not found.",
    "retryable": false
  }
}
409The resource state conflicts with the request, including idempotency-key reuse with a different canonical request hash.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

409 example
{
  "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
  }
}
415The request body is not application/json.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

415 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "input",
    "code": "invalid_request",
    "httpStatus": 415,
    "message": "Content-Type must be application/json.",
    "retryable": false
  }
}
422The body is valid JSON but its document source, template, locale, or output configuration cannot be accepted.

Response headers

X-Correlation-Id

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

422 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "input",
    "code": "invalid_request",
    "httpStatus": 422,
    "message": "The document source or publication options are invalid.",
    "retryable": false
  }
}
429The request is temporarily rate limited. No final publication unit is consumed.

Response headers

X-Correlation-IdRetry-After

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

429 example
{
  "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
  }
}
503A transient publishing, queue, renderer, or storage dependency is unavailable. No failed render consumes a final publication unit.

Response headers

X-Correlation-IdRetry-After

Response schema

PublishingErrorEnvelope

Publishing Error Envelope object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

error
objectrequired

Error value.

503 example
{
  "contractVersion": "publishing.lifecycle.v1",
  "error": {
    "category": "internal",
    "code": "service_unavailable",
    "details": {
      "retryAfterSeconds": 30
    },
    "httpStatus": 503,
    "message": "Publishing is temporarily unavailable.",
    "retryable": true
  }
}

Checking API access

Loading your activation state.