Skip to main content
Use the Agent API to give Krea Agent a task from your own application. Requests and responses use camelCase JSON fields. The Agent works in the background while your application reads its progress and results.
The Agent works in the background. It does not ask questions, and cost and permission prompts are approved automatically. Include all requirements and constraints in your prompt. Review the task before submitting it.

Authentication, access, and billing

Send Authorization: Bearer KREA_API_KEY with every request to https://api.krea.ai. Personal, service, and legacy API keys use the standard public API authentication. You can only read or continue sessions owned by the authenticated caller in the authenticated workspace. Knowing a session ID does not grant access. Krea file attachments must also be accessible to that caller in that workspace.
Agent turns use the workspace’s compute unit balance. They do not use the API balance. Agent plan entitlements and Free plan message limits still apply. See Agent plans, access, and credits.
Each response includes a url where you can open the session in the Krea app with the appropriate account and workspace access.

Start a session and wait for its result

Set KREA_API_KEY in your environment first. Choose Bash with curl and jq, Python with requests, or Node.js with built-in fetch or the Krea SDK.
1

Submit the first turn

Omit sessionId to create a session. Save the returned sessionId and runId. The response returns immediately with status: "running".
2

Wait for this turn

Pass both IDs to wait-for-session. If timedOut is true, call it again with the same IDs. A timeout does not cancel the turn.
3

Read the result

Check status when finished is true. Inspect text, media, and any error, or open the returned url.
For Python, install requests with pip install requests. For Node.js, use Node.js 22+ and save the example as example.mjs. The SDK example requires npm install @krea-ai/sdk and uses requestRaw to call the HTTP endpoints. These examples submit one message and wait for up to five minutes. They stop on HTTP errors and failed or cancelled turns. They never retry a send automatically. If a send request times out, check the session in Krea before submitting again; the first request may have started a turn. When the wait budget expires, the turn continues in the background. Save the printed session and run IDs to resume waiting later. timeoutSeconds is an integer from 1 to 300 and defaults to 60. Keep your HTTP client timeout longer than the requested wait. Always pass the latest runId when waiting after a send, so a previous turn’s terminal status is not mistaken for the new turn.

Read without waiting

Use GET /agent/session/{sessionId} to take a snapshot of the current session:
cURL

Continue the session

After the turn finishes, send another message with its sessionId:
cURL
A session runs one turn at a time. Sending another message while a turn is running returns 409 with code: "conflict".

Inputs and attachments

send-message accepts these fields. See the reference for the full model enum and schemas. Attachment url accepts an accessible HTTP(S) URL or an authorized Krea Files URI such as file:550e8400-e29b-41d4-a716-446655440000. Optional name and contentType are trimmed, nonempty strings of up to 255 characters. Caller-local paths and OpenAI file_ IDs are not supported. Transfer the actual file first; an ID in prompt text does not transfer its contents. The Agent does not inherit your application’s conversation or attachments. Attach reference files that are not otherwise accessible. You do not need to repeat usable URLs in the prompt, existing Krea context, or prior session files.

Session results

send-message returns sessionId, threadId, runId, status (always "running"), and url. GET /agent/session/{sessionId} and wait-for-session return the following session view. Only wait-for-session adds the required timedOut field. Each media item can represent a generation (jobId and optional mediaKind: image, video, audio, or 3d), rehosted media (url, with optional mimeType), or a Krea file (uri, name, mimeType). Fetch generation details through GET /jobs/{jobId}. You can reuse a Krea file URI as an attachment or open the session’s url to view its files. Media can appear while the turn is still running.

Errors

Endpoint errors use { "error": "...", "code": "...", "allowedModels": ["..."] }. Only error is required. A turn that fails after submission appears as status: "failed" in a successful session response instead.