Jobs

Cancel a publishing job

Cancel accepted, queued, or running work. Repeating a successful cancellation returns the same terminal job without a second effect.

POST/api/v2/jobs/{jobId}/cancel

Required scopedocuments.render

Parameters

jobId

pathstring<uuid>required

Owner-scoped publishing job 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

This operation does not accept a request body.

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

Cancellation releases an uncommitted final reservation and leaves safe job metadata for 30 days. Existing artifacts are unaffected and remain deletable through the document. Response field: retention.

Responses

200The job is already cancelled or terminal.

Response headers

X-Correlation-IdIdempotency-Replayed

Response schema

JobResponse

Job Response object used by the Publishing API.

artifact

ArtifactSummary | nullrequired

Artifact value.

contractVersion

stringrequired

Contract Version value.

job

objectrequired

Job value.

links

objectrequired

Links value.

warnings

array<Warning>required

Warnings value.

Maximum items: 100

200 example

{
  "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-22.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-22.1",
      "channel": "rest_v2",
      "engineVersion": "1.0.2",
      "fontSetSha256": null,
      "locale": "en",
      "manifestSha256": null,
      "optionsSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "renderOptionsSha256": null,
      "rendererReleaseChecksum": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "rendererVersion": "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": []
}

202Cancellation was accepted; a leased worker is being fenced or drained.

Response headers

X-Correlation-IdIdempotency-Replayed

Response schema

JobResponse

Job Response object used by the Publishing API.

artifact

ArtifactSummary | nullrequired

Artifact value.

contractVersion

stringrequired

Contract Version value.

job

objectrequired

Job value.

links

objectrequired

Links value.

warnings

array<Warning>required

Warnings value.

Maximum items: 100

202 example

{
  "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-22.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-22.1",
      "channel": "rest_v2",
      "engineVersion": "1.0.2",
      "fontSetSha256": null,
      "locale": "en",
      "manifestSha256": null,
      "optionsSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "renderOptionsSha256": null,
      "rendererReleaseChecksum": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "rendererVersion": "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": []
}

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
  }
}

Request

curl --request POST \
  "https://markdowntopdfconverter.com/api/v2/jobs/${JOB_ID}/cancel" \
  -H "Authorization: Bearer $MD2PDF_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

Response

200 The job is already cancelled or terminal.

{
  "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-22.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-22.1",
      "channel": "rest_v2",
      "engineVersion": "1.0.2",
      "fontSetSha256": null,
      "locale": "en",
      "manifestSha256": null,
      "optionsSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "renderOptionsSha256": null,
      "rendererReleaseChecksum": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "rendererVersion": "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": []
}