Start agent run - Erstan

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>"
  }
}

POST

/

v1

/

public

/

agents

/

{agentId}

/

runs

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

Authorization

string

header

required

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

agentId

string

required

Agent workflow ID returned by GET /v1/public/agents.

Body

application/json

Request body for starting an asynchronous agent run.

input

object

required

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.

laneId

string

Required when the agent has multiple public lanes. Omit only when defaultLaneId is present.

attachments

object[]

Optional attachments. Each item needs name, type, and either base64 or storageKey.

Option 1
Option 2

Show child attributes

metadata

object

Caller metadata stored with the run, such as source system and NetSuite record URL.

idempotencyKey

string

Reuse to prevent duplicate runs on retries.

Maximum string length: 200

Response

Existing run returned for a matching idempotency key.

runId

string<uuid>

required

agentId

string

required

laneId

string

required

status

enum<string>

required

Available options:

running,

cancelling,

waiting,

completed,

failed,

cancelled