​
Schedule a new task

Creates a new Data Processor task of verified custom module execution with Atlantic submission and on-chain commitment.

​
Endpoint

POST /tasks

​
Request Body

FieldTypeDescription
destination_chain_idintegerThe chain ID where the task will be proven
webhook_urlstringOptional URL to receive task completion/failure notifications
inputobjectThe task input parameters
input.paramsarrayArray of parameters for the contract execution
input.compiled_classobjectThe custom module compiled contract class
input.entry_points_by_typeobjectEntry points configuration for different types
input.entry_points_by_type.EXTERNALarrayArray of external entry points
input.entry_points_by_type.L1_HANDLERarrayArray of L1 handler entry points
input.entry_points_by_type.CONSTRUCTORarrayArray of constructor entry points

​
Example Request

curl -X POST https://staging.hdp.api.herodotus.cloud/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-herodotus-cloud-api-key-here" \
  -d '{
    "destination_chain_id": 11155111,
    "webhook_url": "https://your-domain.com/webhook",
    "input": {
        "params": [],
        "compiled_class": {
            <<INSERT_COMPILED_CLASS>>
        },
        "entry_points_by_type": {
            "EXTERNAL": [
                {
                    "selector": "0xe2054f8a912367e38a22ce773328ff8aabf8082c4120bad9ef085e1dbf29a7",
                    "offset": 0,
                    "builtins": [
                        "range_check"
                    ]
                }
            ],
            "L1_HANDLER": [],
            "CONSTRUCTOR": []
        }
    }
}'

​
Response

​
Success Response (200 OK)

{
  "message": "Task has been queued for processing",
  "status": "accepted",
  "uuid": "01JPJ03YJT1A93D6NF56G4GVEQ"
}

​
Error Response (401 Unauthorized)

{
  "error": "Missing Herodotus Cloud X-API-KEY header"
}

​
Error Responses

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid authentication
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error

​
Webhook Notifications

When a webhook_url is provided, the service will send a POST request to the specified URL when the task completes or fails. The webhook payload will be sent as JSON.

​
Success Webhook Payload

{
  "status": "TaskDecommitmentCompleted",
  "task_id": "01JPMW7VE29Z0EH1VZKJPSCFR4",
  "timestamp": "2025-03-18T15:01:01.303281+00:00",
  "transaction_hash": "0xcfb8…6f98"
}

​
Failure Webhook Payload

{
  "task_id": "01JPMW7VE29Z0EH1VZKJPSCFR4",
  "status": "TraceGenFailed",
  "error": "cairo-compile was not found",
  "timestamp": "2025-03-18T17:01:01.303281+00:00"
}

​
Webhook Payload Fields

FieldTypeDescription
statusstringFinal status of the task
task_idstringThe unique identifier of the task
timestampstringISO 8601 timestamp of the status update
transaction_hashstringHash of the transaction (only present in success payload)
errorstringError message (only present in failure payload)

​
Notes

  • The compiled_class field should contain the complete compiled contract class data from the custom module
  • Entry points are used to define the contract’s interface and execution points
  • The selector field in entry points is a hash of the encoded function name
  • Builtins specify the required built-in functions for the contract execution
  • The uuid in the response can be used to check the task status using the status endpoint
  • Webhook notifications are sent asynchronously after task completion or failure
  • The webhook endpoint should be publicly accessible and respond with a 2xx status code