Schedule a new task

Create and submit a Data Processor task for verified custom module execution with onchain commitment

Schedule a new task

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

Endpoint

POST /tasks

Request Body

Field	Type	Description
destination_chain_id	integer	The chain ID where the task will be proven
webhook_url	string	Optional URL to receive task completion/failure notifications
input	object	The task input parameters
input.params	array	Array of parameters for the contract execution
input.compiled_class	object	The custom module compiled contract class
input.entry_points_by_type	object	Entry points configuration for different types
input.entry_points_by_type.EXTERNAL	array	Array of external entry points
input.entry_points_by_type.L1_HANDLER	array	Array of L1 handler entry points
input.entry_points_by_type.CONSTRUCTOR	array	Array 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

Field	Type	Description
status	string	Final status of the task
task_id	string	The unique identifier of the task
timestamp	string	ISO 8601 timestamp of the status update
transaction_hash	string	Hash of the transaction (only present in success payload)
error	string	Error 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