API and webhook
Trigger and follow Production runs of the code project through the public API, authenticated by a workspace API key.
API and webhook
External systems can trigger the project through Roberty's public API, send arguments and fetch the result. These runs use the Webhook trigger and always run in Production. The project settings, API & Webhook tab, show the endpoints, a request example and the Postman collection.
Credential
Every request carries the x-roberty-api-key header with a workspace API key whose Code projects scope covers this project.
Only workspace administrators create and manage API keys. The key is shown only once, at creation — store it somewhere safe.
The endpoints' {codeId} is the Project ID, shown in Settings, General tab.
Endpoints
| Step | Endpoint | Purpose |
|---|---|---|
| 1 | GET https://api.roberty.app/v4/public/webhook/code/arguments/{codeId} | Discover arguments: returns the inputs and outputs declared in the webhook section of the roberty.json of the active Production deployment. |
| 2 | POST https://api.roberty.app/v4/public/webhook/code/request/{codeId} | Run: creates a Production run with the arguments sent and answers 202 with requestId and deviceId. |
| 3 | GET https://api.roberty.app/v4/public/webhook/code/response/{requestId} | Get result: returns the run status and, on success, the result the robot wrote. |
1. Discover arguments
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/arguments/$CODE_ID
2. Run
The body has args, which becomes the JSON of the robot's arguments file, and an optional deviceId.
curl -X POST -H "x-roberty-api-key: $ROBERTY_API_KEY" -H "content-type: application/json" \
-d '{ "args": { "cpf": "12345678900" } }' \
https://api.roberty.app/v4/public/webhook/code/request/$CODE_ID
{ "requestId": "…", "deviceId": "…" }
3. Get result
Poll until the status is success or failure.
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/response/$REQUEST_ID
{
"requestId": "…",
"deviceId": "…",
"status": "success",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 1234,
"response": { "status": "ok", "processedAt": "…" }
}
| Field | Description |
|---|---|
status | pending, running, success or failure. |
response | Only on success: what the robot wrote to the roberty-output-file-path file. Valid JSON comes back as an object; text that isn't JSON comes back as a string. If the robot wrote nothing, the field is absent. |
outputTruncated | true when the result exceeded 256 KB and was cut. |
error | Only on failure: the error message. On failure, the result is not sent. |
startedAt, finishedAt, durationMs | The run's start, end and duration, when available. |
Arguments and webhook.inputs
The webhook section of roberty.json documents the robot's contract: which keys it reads (inputs) and which it writes (outputs). The platform uses this declaration in the Discover arguments endpoint and to build the request example and the Postman collection. See The webhook section.
- If an input marked
requiredis missing fromargs, the trigger fails with400and theMISSING_REQUIRED_INPUT_ARGUMENTerror, naming the missing inputs. Nothing is sent to the device. - Types and extra keys are not validated: the
argsreach the robot exactly as sent. - With no declared inputs, the
argsalso arrive as sent — there is just no published contract.
Device selection and queueing
- Without
deviceId— the platform picks, among the online Production devices with an active deployment, the one with the fewest pending runs of the project. - With
deviceId— the run is pinned to that device, which must be a Production device, online and with an active deployment.
Each device runs one run of the project at a time: back-to-back triggers are queued and run as soon as the device is free. The Preview device never receives API runs.
Errors
| Situation | Result |
|---|---|
| No active deployment in Production | The endpoint answers 409. Deploy to Production for the webhook to answer. See Deployments. |
Missing required input | 400 with MISSING_REQUIRED_INPUT_ARGUMENT. |
| No Production device online | 503 with NO_DEVICE_ONLINE. See Devices. |
| Project turned off | Triggers are blocked until the project is turned back on in Settings. |
Testing in Postman
On the API & Webhook tab, Download collection builds a Postman collection with the three endpoints, the headers and a body built from the declared inputs. The collection uses the YOUR_API_KEY placeholder: replace it with a key that has the Code projects scope.
How the robot takes part
- The run happens with
roberty-triggerset towebhook, and theargsarrive in theroberty-args-file-pathfile. - Whatever the robot writes to the
roberty-output-file-pathfile comes back inresponsewhen the process exits with code0.
See also
- Run Code project — run the project from an RPA robot.
- API keys
- Runs