> ## Documentation Index > Fetch the complete documentation index at: https://docs.erstan.com/llms.txt > Use this file to discover all available pages before exploring further. # Start agent run > Starts an asynchronous run for a selected public lane. `laneId` may be omitted only when the agent has one public lane. ## OpenAPI ````yaml /openapi/public-api.yaml post /v1/public/agents/{agentId}/runs openapi: 3.1.0 info: title: Erstan Public Agent API version: 1.2.0 description: >- Start published Erstan agents from external systems and poll for results. API 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 and team permissions. Project and team allowlists (`allowedProjectIds`, `allowedTeamIds`) further restrict task and document and file access. Agent draft authoring and task/document/file tools are exposed through the MCP server at `/v1/mcp` rather than REST routes. servers: - url: https://api.erstan.com description: Public endpoint security: - PublicApiKey: [] tags: - name: Agents description: >- Discover and run published agents available to the key creator under their current permissions. - name: Runs description: Read run status and results. - name: MCP description: >- Model Context Protocol server for external clients. Agent Builder tools use `agents:read`, `agents:write`, or both, plus the key creator's live Erstan permissions. Task and content tools also apply project/team allowlists. paths: /v1/public/agents/{agentId}/runs: post: tags: - Agents summary: Start agent run description: >- Starts an asynchronous run for a selected public lane. `laneId` may be omitted only when the agent has one public lane. operationId: createPublicAgentRun parameters: - name: agentId in: path required: true description: Agent workflow ID returned by `GET /v1/public/agents`. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRunRequest' examples: singleLaneStructured: summary: Structured run for a single-lane agent value: 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 explicitLaneWithAttachment: summary: OCR quote intake with an attachment value: laneId: start_ocr_quote_intake input: sourceRecordType: customrecord_email_plugin_message sourceRecordId: '98342' senderEmail: orders@examplecustomer.com emailSubject: PO request attached emailBody: Hi, quote attached. The customer uses our old part codes. customerHint: Example Customer contactHint: orders@examplecustomer.com attachments: - name: customer-request.pdf type: application/pdf base64: JVBERi0xLjQK... idempotencyKey: netsuite-email-plugin-quote-98342 metadata: sourceSystem: netsuite automation: ar_quote_intake chatLane: summary: Chat lane run value: laneId: start_quote_chat input: message: Summarize the quote request in this email body. idempotencyKey: quote-chat-98342 responses: '200': description: Existing run returned for a matching idempotency key. content: application/json: schema: $ref: '#/components/schemas/CreateRunResponse' examples: existing: value: runId: 0cfd96a4-3e9b-40f2-9a62-8b5ec8ab19f8 agentId: clx_agent_123 laneId: start_ocr_quote_intake status: running '202': description: Run accepted and started. content: application/json: schema: $ref: '#/components/schemas/CreateRunResponse' examples: accepted: value: runId: 0cfd96a4-3e9b-40f2-9a62-8b5ec8ab19f8 agentId: clx_agent_123 laneId: start_ocr_quote_intake status: running '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - PublicApiKey: [] components: schemas: CreateRunRequest: type: object additionalProperties: false required: - input description: Request body for starting an asynchronous agent run. properties: laneId: type: string description: >- Required when the agent has multiple public lanes. Omit only when `defaultLaneId` is present. input: type: object additionalProperties: true description: >- 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. x-erstan-runtime-controls: errorCode: reserved_input_field representativeReservedFields: - tools - toolPolicy - writePolicy - autoApproveWrites - runtimeApprovalMode - skillPolicy - skillIds - model - providerSlug - contextType - workflowContextId attachments: type: array description: >- Optional attachments. Each item needs `name`, `type`, and either `base64` or `storageKey`. items: $ref: '#/components/schemas/Attachment' metadata: type: object additionalProperties: true description: >- Caller metadata stored with the run, such as source system and NetSuite record URL. idempotencyKey: type: string maxLength: 200 description: Reuse to prevent duplicate runs on retries. CreateRunResponse: type: object required: - runId - agentId - laneId - status properties: runId: type: string format: uuid agentId: type: string laneId: type: string status: $ref: '#/components/schemas/RunStatus' Attachment: type: object additionalProperties: false required: - name - type properties: name: type: string type: type: string description: Content type, such as `application/pdf`. base64: type: string description: Base64-encoded file content. storageKey: type: string description: Existing Erstan storage key, when already uploaded. anyOf: - required: - base64 - required: - storageKey RunStatus: type: string enum: - running - cancelling - waiting - completed - failed - cancelled ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' requestId: type: string ErrorDetail: type: object required: - code - message properties: field: type: string code: type: string message: type: string responses: BadRequest: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing, invalid, expired, revoked, or inactive API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks scope or the creator lacks current permission for the requested operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested agent or run was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: ers_live API key description: >- 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. ````