Generate documents over REST

At the end a system outside Salesforce requests PDF and Word documents with one JSON call and follows each run to its Files. For integration developers.

Before you start

• You have an OAuth access token for a user with Docable Generate and Docable Runtime Generator Storage, and your My Domain URL.
• The resource is POST /services/apexrest/docable/v1/. In an installed package the path carries the package namespace.

Steps

1. Send a JSON envelope to the resource with Authorization: Bearer <token>.
2. Set apiVersion to "1", operation to requestGeneration, and requestId to a new lowercase UUID.
3. In arguments, give the template and the records, and the outputs. Optional: "brandKit" names one of the template’s Brand Kits for every document; a kit the template doesn’t allow is refused with the allowed kits named.
4. Read the answer. HTTP 200 with "status": "Completed" means the documents were made in the request. HTTP 202 with "status": "Accepted" means the run was queued: GET /services/apexrest/docable/v1/generations/<operationRef> until completed is true.
5. To cancel or retry, send the same envelope with operation set to cancelGeneration or retryGeneration and arguments of {"runId": "..."}.

Every argument and answer field is in Generation request and result fields.

Example

curl -s -X POST "$INSTANCE/services/apexrest/docable/v1/" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "1",
    "operation": "requestGeneration",
    "requestId": "6f1c2d3e-4a5b-4c6d-8e7f-90a1b2c3d4e5",
    "arguments": {
      "templateId": "a07XXXXXXXXXXXXXXX",
      "recordIds": ["0WOXXXXXXXXXXXXXXX"],
      "outputs": ["PDF", "DOCX"]
    }
  }'

Follow a queued run, or cancel one:

curl -s "$INSTANCE/services/apexrest/docable/v1/generations/<runId>" -H "Authorization: Bearer $TOKEN"

curl -s -X POST "$INSTANCE/services/apexrest/docable/v1/" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"apiVersion":"1","operation":"cancelGeneration","requestId":"<new uuid>","arguments":{"runId":"<runId>"}}'

The answer is {apiVersion, requestId, correlationId, status, result, issues, nextAction, operationRef}.

Check it worked

A single record answers HTTP 200 with status Completed, and result.items[].outputs[] carry each File’s contentDocumentId. Reading a finished run with GET answers Completed, and its combined PDF is present when you asked for one.

If it doesn’t work

What you see	What to do
status is Refused.	Read issues[0]: its category, code and message. The HTTP code follows the category: see Error and reason codes.
The request is refused for an unknown property or argument.	Unknown properties, arguments, operations and API versions are refused, and flags must be JSON booleans.
The same request makes a second run.	Send a new lowercase UUID as requestId for each request. The same id returns the same run. The same id with a different request is refused with GENERATION_REQUEST_KEY_REUSED.

Next

• Generation request and result fields
• Connect Claude to Docable