Generation
Overview
Generation runs a stateless Agent Turn without creating Session history. Use it for one-shot text or JSON-schema-constrained output when later continuation is unnecessary.
Endpoints
POST /v1/agents/:agentId/generation
Runs one stateless turn with no Session or history. Both output modes return a plain text stream. Structured output constrains object-mode text to JSON matching the supplied JSON Schema. An Agent with no file tools needs no Sandbox. An Agent selecting file_operation_sandbox uses its attached durable Sandbox; the Sandbox belongs to the Agent rather than a Session. Stateless turns cannot save Artifacts.
Request
Requires bearer authentication and JSON. agentId is a required ag_… path parameter. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.
| Location | Field | Required | Description |
|---|---|---|---|
| Header | Authorization | yes | Tenant API key or dashboard Supabase JWT. |
| Path | agentId | yes | Agent ID (ag_…). |
Provide exactly one of prompt or promptId. variables is allowed only with promptId.
| Body field | Type | Required | Description |
|---|---|---|---|
prompt | string | alternative | Non-empty literal prompt |
promptId | string | alternative | Stored Prompt ID |
variables | object<string,string> | no | Exact stored Prompt variables |
output | object | yes | { "type": "text" } or { "type": "object", "schema": {…} } |
userId | string | no | Usage attribution; defaults to "" |
metadata | object | no | Usage metadata; defaults to {} |
version | integer | no | Immutable Agent Version; defaults to the current Version |
Response
Returns 200 OK as text/plain with an AI SDK text stream. Text mode streams text; object mode streams JSON text. See the streaming protocol for transport and cancellation behavior.
Password resets are available from Settings > Security.Errors
400 invalid_request for invalid prompt/output selection, Prompt variables, or missing platform-key configuration. 404 not_found applies to a missing Agent, Provider, Prompt, or pinned Version (AGENT_VERSION_NOT_FOUND). 409 AGENT_DISABLED or 409 SANDBOX_REQUIRED can reject execution. 429 quota_exceeded and 502 provider_error may occur. A failure detected before streaming returns its non-2xx status with the standard JSON error envelope. After the 200 plain-text stream starts, a failure terminates the body; it cannot change the status or emit a JSON envelope, and this endpoint does not use the UI-message error chunks produced by Session streams. See REST errors.
cURL
curl --no-buffer --request POST \
"$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/generation" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
--header "Content-Type: application/json" \
--data '{"prompt":"Explain password resets in one sentence.","output":{"type":"text"}}'SDK and related guides
SDK: completion for text and object for structured output. See Generation and streaming and Generate structured output.