API and webhook
Process documents with an IDP template through the public API: request the run, upload the document to the signed URL and fetch the result.
API and webhook
External systems can process documents with the template through Roberty's public API. The call takes three steps: request the run, upload the document and fetch the result. These runs always use the active version and show in the Production environment, in Runs.
The API & Webhook section of the template settings shows the endpoints with the template ID already filled in, a body example and the Postman collection.
The workspace plan must include IDP requests and webhooks. Every processed document counts toward the workspace's IDP requests usage; a requested run whose document was never uploaded does not count.
Credential
Requests for steps 1 and 3, and the discovery request, carry the x-roberty-api-key header with a workspace API key whose IDP templates scope covers this template. The document upload (step 2) does not carry the header: the URL is already signed.
Only workspace administrators create and manage API keys. The key is shown only once, at creation — store it somewhere safe.
Endpoints
| Step | Endpoint | What for |
|---|---|---|
| 1 | POST https://api.roberty.app/v4/public/webhook/idp/request/{templateId} | Request the run: reserves the run and returns the requestId and the temporary URL to upload the document. |
| 2 | PUT {uploadUrl} | Upload the document: the file's bytes go to the URL returned in step 1. This upload is what triggers processing. |
| 3 | GET https://api.roberty.app/v4/public/webhook/idp/response/{requestId} | Track and get the result: returns the run's status and, once finished, the result. |
| — | GET https://api.roberty.app/v4/public/webhook/idp/arguments/{templateId} | Discover the contract: returns the accepted formats and what the active version expects to receive. |
1. Request the run
| Body field | Required | Description |
|---|---|---|
filename | Yes | The file name. The extension sets how the document is read and must be pdf, png, jpg, jpeg, webp, tiff, tif or bmp. |
page | No | The page range for this run, for example 1-3,5, instead of the scope configured in the template. Only accepted when the active version lets the API override the pages. See Document and pages. |
params | No | An object with parameters the pipeline can use, for example in post-processing steps. See Post-processing. |
curl -X POST -H "x-roberty-api-key: $ROBERTY_API_KEY" -H "content-type: application/json" \
-d '{ "filename": "documento.pdf", "params": {} }' \
https://api.roberty.app/v4/public/webhook/idp/request/$TEMPLATE_ID
The response has status 202:
{
"requestId": "…",
"uploadUrl": "https://…",
"expiresAt": "…"
}
2. Upload the document
Send the file's bytes with PUT to the uploadUrl, without the API key header. The URL is valid for 15 minutes.
curl -X PUT --upload-file documento.pdf "$UPLOAD_URL"
As soon as the upload finishes, the run is queued and the pipeline starts.
3. Track and get the result
Poll until the status is finished, error or expired.
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/response/$REQUEST_ID
{
"requestId": "…",
"templateId": "…",
"versionId": "…",
"status": "finished",
"createdAt": "…",
"uploadedAt": "…",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 9000,
"result": { "…": "…" }
}
| Status | Meaning |
|---|---|
waiting_upload | The run was reserved and is waiting for the document upload. |
pending | The document arrived and the run is waiting to start. |
running | The pipeline is processing the document. |
finished | The pipeline reached the end. This includes documents rejected by identification and results that failed validations. |
error | The run failed. The message comes in error. |
expired | The document was not uploaded in time and the reservation expired. |
| Field | Description |
|---|---|
result | Only on finished: each stage's result — preProcessing, identification, extraction, postProcessing and validations — and the total time in totalMs. The final output is the output of the last postProcessing item or, with no post-processing, extraction.text. |
error | Only on error: the pipeline's failure message. |
versionId | The version that processed the document. |
durationMs | The time between the document upload and the end of the run. |
When identification rejects the document, result.identification.passed is false and the following stages don't run. Each validation's verdict comes in result.validations, with passed and reason. See Identification and Validations.
Discover the contract
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/arguments/$TEMPLATE_ID
Returns the template name, the active version number, the accepted file extensions (inputs.file.accept) and whether the call may send page (inputs.page.allowed), along with the range configured in the template (inputs.page.configuredRange).
Errors
| Status | Error | Situation |
|---|---|---|
400 | UNSUPPORTED_FILE_EXTENSION | The filename extension is not accepted. |
400 | PAGE_OVERRIDE_NOT_ALLOWED | The call sent page, but the active version does not let the API override the pages. |
403 | API_KEY_NOT_AUTHORIZED_FOR_THIS_TEMPLATE | The API key does not have the IDP templates scope for this template. |
404 | TEMPLATE_NOT_FOUND | The template does not exist in this workspace. |
404 | REQUEST_NOT_FOUND | The requested requestId does not exist or does not belong to this workspace. |
409 | NO_ACTIVE_VERSION | The template has no active version. Publish one in Versions. |
409 | STORAGE_LIMIT_REACHED | The workspace has reached its storage limit. |
When the template has no active version yet, the API & Webhook section shows a notice.
Test in Postman
In the API & Webhook section, Download collection builds a Postman collection with the four endpoints and a sample body. The collection uses the YOUR_API_KEY placeholder: replace it with a key that has the IDP templates scope. Fill the requestId and uploadUrl variables with the values returned by step 1 and, in step 2, select the file in the Body tab (binary).
The collection's body always shows the page field. Remove it if the template does not let the API override the pages. The section's Request example already shows the right body for the template.
To try the call without an API key and without publishing, use Simulate API, which runs the draft. See Playground and Simulate API.