Skip to main content
Roberty Studio
CODECode

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.

info

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​

StepEndpointPurpose
1GET 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.
2POST 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.
3GET 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​

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

bash
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
json
{ "requestId": "…", "deviceId": "…" }

3. Get result​

Poll until the status is success or failure.

bash
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/response/$REQUEST_ID
json
{
"requestId": "…",
"deviceId": "…",
"status": "success",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 1234,
"response": { "status": "ok", "processedAt": "…" }
}
FieldDescription
statuspending, running, success or failure.
responseOnly 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.
outputTruncatedtrue when the result exceeded 256 KB and was cut.
errorOnly on failure: the error message. On failure, the result is not sent.
startedAt, finishedAt, durationMsThe 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 required is missing from args, the trigger fails with 400 and the MISSING_REQUIRED_INPUT_ARGUMENT error, naming the missing inputs. Nothing is sent to the device.
  • Types and extra keys are not validated: the args reach the robot exactly as sent.
  • With no declared inputs, the args also 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​

SituationResult
No active deployment in ProductionThe endpoint answers 409. Deploy to Production for the webhook to answer. See Deployments.
Missing required input400 with MISSING_REQUIRED_INPUT_ARGUMENT.
No Production device online503 with NO_DEVICE_ONLINE. See Devices.
Project turned offTriggers 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-trigger set to webhook, and the args arrive in the roberty-args-file-path file.
  • Whatever the robot writes to the roberty-output-file-path file comes back in response when the process exits with code 0.

See Preparing the project.

See also​