curl --request POST \
--url https://api.erstan.com/v1/public/agents/{agentId}/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": {
"sourceRecordType": "customrecord_email_plugin_message",
"sourceRecordId": "98342",
"senderEmail": "orders@examplecustomer.com",
"emailSubject": "Quote request",
"emailBody": "Please quote 12 of competitor part ABC-100."
},
"idempotencyKey": "netsuite-email-plugin-quote-98342",
"metadata": {
"sourceSystem": "netsuite"
}
}
'{
"runId": "0cfd96a4-3e9b-40f2-9a62-8b5ec8ab19f8",
"agentId": "clx_agent_123",
"laneId": "start_ocr_quote_intake",
"status": "running"
}{
"runId": "0cfd96a4-3e9b-40f2-9a62-8b5ec8ab19f8",
"agentId": "clx_agent_123",
"laneId": "start_ocr_quote_intake",
"status": "running"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}Start agent run
Starts an asynchronous run for a selected public lane. laneId may be omitted only when the agent has one public lane.
curl --request POST \
--url https://api.erstan.com/v1/public/agents/{agentId}/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": {
"sourceRecordType": "customrecord_email_plugin_message",
"sourceRecordId": "98342",
"senderEmail": "orders@examplecustomer.com",
"emailSubject": "Quote request",
"emailBody": "Please quote 12 of competitor part ABC-100."
},
"idempotencyKey": "netsuite-email-plugin-quote-98342",
"metadata": {
"sourceSystem": "netsuite"
}
}
'{
"runId": "0cfd96a4-3e9b-40f2-9a62-8b5ec8ab19f8",
"agentId": "clx_agent_123",
"laneId": "start_ocr_quote_intake",
"status": "running"
}{
"runId": "0cfd96a4-3e9b-40f2-9a62-8b5ec8ab19f8",
"agentId": "clx_agent_123",
"laneId": "start_ocr_quote_intake",
"status": "running"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"requestId": "<string>"
}
}Authorizations
Workspace API key created in Erstan Settings. Keys carry scopes (agents:list, agents:read, agents:write, agents:run, runs:read, tasks:execute, documents:read, documents:write, files:read, files:write). Agent access follows the key creator's current workspace, team, and agent permissions. Agent draft creation requires agents:write; update, validation, and publishing require both agents:read and agents:write; draft testing also requires agents:run. Keys with tasks:execute must include at least one allowed project or team (allowedProjectIds / allowedTeamIds); keys with document or file scopes must include at least one allowed team. Empty allowlists mean no access — the API fails closed.
Path Parameters
Agent workflow ID returned by GET /v1/public/agents.
Body
Request body for starting an asynchronous agent run.
Business input validated against the selected lane's inputSchema. Top-level reserved runtime-control keys for tools, tool and skill policies, writes/approvals, models/providers, and workflow/context selectors are controlled by the saved agent definition. Supplying one returns reserved_input_field and does not start a run.
Required when the agent has multiple public lanes. Omit only when defaultLaneId is present.
Optional attachments. Each item needs name, type, and either base64 or storageKey.
- Option 1
- Option 2
Show child attributes
Show child attributes
Caller metadata stored with the run, such as source system and NetSuite record URL.
Reuse to prevent duplicate runs on retries.
200