Skip to main content
Roberty Studio
IDPSettings

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.

info

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​

StepEndpointWhat for
1POST 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.
2PUT {uploadUrl}Upload the document: the file's bytes go to the URL returned in step 1. This upload is what triggers processing.
3GET 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 fieldRequiredDescription
filenameYesThe file name. The extension sets how the document is read and must be pdf, png, jpg, jpeg, webp, tiff, tif or bmp.
pageNoThe 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.
paramsNoAn object with parameters the pipeline can use, for example in post-processing steps. See Post-processing.
bash
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:

json
{
"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.

bash
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.

bash
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/response/$REQUEST_ID
json
{
"requestId": "…",
"templateId": "…",
"versionId": "…",
"status": "finished",
"createdAt": "…",
"uploadedAt": "…",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 9000,
"result": { "…": "…" }
}
StatusMeaning
waiting_uploadThe run was reserved and is waiting for the document upload.
pendingThe document arrived and the run is waiting to start.
runningThe pipeline is processing the document.
finishedThe pipeline reached the end. This includes documents rejected by identification and results that failed validations.
errorThe run failed. The message comes in error.
expiredThe document was not uploaded in time and the reservation expired.
FieldDescription
resultOnly 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.
errorOnly on error: the pipeline's failure message.
versionIdThe version that processed the document.
durationMsThe 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​

bash
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​

StatusErrorSituation
400UNSUPPORTED_FILE_EXTENSIONThe filename extension is not accepted.
400PAGE_OVERRIDE_NOT_ALLOWEDThe call sent page, but the active version does not let the API override the pages.
403API_KEY_NOT_AUTHORIZED_FOR_THIS_TEMPLATEThe API key does not have the IDP templates scope for this template.
404TEMPLATE_NOT_FOUNDThe template does not exist in this workspace.
404REQUEST_NOT_FOUNDThe requested requestId does not exist or does not belong to this workspace.
409NO_ACTIVE_VERSIONThe template has no active version. Publish one in Versions.
409STORAGE_LIMIT_REACHEDThe 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.

See also​