Markdown to PDF
5 PDFs free

API documentation

Create a managed document

Documents

Create a managed document

Create an owner-scoped managed document and its first immutable revision. This does not render or consume a final publication unit.

POST/api/v2/documents
Required scopedocuments.render

Parameters

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.

CreateDocumentRequest

Create Document Request object used by the Publishing API.

revision
objectrequired

Revision value.

taskId
stringrequired

Task Id value.

  • Minimum length: 1
  • Maximum length: 100
  • Pattern: ^[a-z0-9][a-z0-9._-]*$
title
string | nullrequired

Title value.

  • Minimum length: 1
  • Maximum length: 160

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

The encrypted source and immutable revision expire 30 days after document activity unless the owner deletes them first. Response field: retention.

Responses

201The document and first immutable revision. A same-key replay returns the identical resource identities.

Response headers

X-Correlation-IdIdempotency-Replayed

Response schema

DocumentResponse

Document Response object used by the Publishing API.

contractVersion
stringrequired

Contract Version value.

document
objectrequired

Document value.

links
objectrequired

Links value.

revision
objectrequired

Revision value.

201 example
{
  "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"
  }
}
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.