> ## 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. # Preview the exact guarded draft > Requires stagedAuthoring, guardedPreviews, agents:read, agents:write and agents:run. This is a real hosted run with possible costs and external effects, not an offline simulation. Admission atomically checks the revision and seals the graph. Later edits/publication fork that snapshot. Optional skillVersions select immutable snapshots outside business input. Each requires current edit access and the Agent's existing Skill scope. Unselected Skills and child Agents remain published. Poll the ordinary run handle using the same API key. Validation and publication are independent. ## OpenAPI ````yaml /openapi/public-api.yaml post /v1/public/authoring/agents/{id}/previews openapi: 3.1.0 info: title: Erstan Public Agent API version: 1.4.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. Guarded Agent and Skill draft authoring is available under `/v1/public/authoring` when the workspace capability is enabled. The MCP server at `/v1/mcp` also exposes authoring and task/document/file tools. servers: - url: https://api.erstan.com description: Public endpoint security: - PublicApiKey: [] tags: - name: Authoring description: >- Capability-gated Agent and Skill drafts, history, validation and publication. - 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/authoring/agents/{id}/previews: post: tags: - Authoring summary: Preview the exact guarded draft description: >- Requires stagedAuthoring, guardedPreviews, agents:read, agents:write and agents:run. This is a real hosted run with possible costs and external effects, not an offline simulation. Admission atomically checks the revision and seals the graph. Later edits/publication fork that snapshot. Optional skillVersions select immutable snapshots outside business input. Each requires current edit access and the Agent's existing Skill scope. Unselected Skills and child Agents remain published. Poll the ordinary run handle using the same API key. Validation and publication are independent. operationId: previewAuthoringAgent parameters: - name: id in: path required: true schema: type: string - name: If-Match in: header required: true schema: type: string - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthoringPreviewRequest' responses: '200': description: Existing accepted preview. content: application/json: schema: $ref: '#/components/schemas/CreateRunResponse' '202': description: Preview accepted. content: application/json: schema: $ref: '#/components/schemas/CreateRunResponse' default: description: >- Public error. Missing revision is 428; stale revision is 412; uncertain outcome is 409 and must be reconciled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: AuthoringPreviewRequest: type: object additionalProperties: false properties: skillVersions: type: array maxItems: 50 items: type: object additionalProperties: false required: - skillId - version properties: skillId: type: string version: type: integer minimum: 1 laneId: type: string input: type: object additionalProperties: true attachments: type: array items: $ref: '#/components/schemas/Attachment' 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' 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 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: - queued - running - cancelling - waiting - completed - failed - cancelled ErrorDetail: type: object required: - code - message properties: field: type: string code: type: string message: type: string 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. ````