---
title: "Send Agent Message"
method: POST
path: "/agent/send-message"
tags: ["Agent"]
---

# Send Agent Message

`POST /agent/send-message`

## Request

- Base URL: `https://api.krea.ai`
- URL: `https://api.krea.ai/agent/send-message`
- Auth: HTTP bearer

Start a Krea Agent session or send a follow-up turn by passing sessionId. Returns immediately while the Agent works in the background. Sessions are visible at the returned url and billed to the workspace's compute unit balance. The Agent does not ask questions, and cost and permission prompts are approved automatically: include all requirements in the prompt. A session runs one turn at a time. Attachments accept http(s) URLs and authorized Krea Files URIs (file:<uuid>). Model pins must be included in the workspace plan.

## Request body

- object
  - `sessionId` string, uuid: Omit to start a new session; pass an existing id to continue it
  - `prompt` string
  - `attachments` object[]: Transfer reference files that are not otherwise accessible to the Agent here. Usable URLs in the prompt, existing Krea context, and prior session files need not be repeated in attachments. The Agent does not inherit your conversation or attachments. Mentioning OpenAI file_ IDs in prompt text does not transfer their bytes, and those IDs cannot be converted to Krea file URIs.
    - `url` union, required: An accessible http(s) URL, or an authorized Krea Files URI "file:<uuid>" from list_files or write_files. OpenAI file_ IDs and caller-local paths are not supported; transfer the actual file first.
      - string, uri
      - string
    - `name` string
    - `contentType` string
  - `model` 'openai/gpt-6-astra' | 'openai/gpt-6.1-sol' | 'openai/gpt-6-sol' | 'openai/gpt-6-luna' | 'openai/gpt-5.6-sol' | 'openai/gpt-5.6-terra' | 'openai/gpt-5.6-luna' | 'openai/gpt-5.5' | 'anthropic/claude-opus-5.5' | 'anthropic/claude-opus-5' | 'anthropic/claude-fable-5.1' | 'anthropic/claude-fable-5' | 'anthropic/claude-opus-4.8' | 'anthropic/claude-sonnet-5' | 'anthropic/claude-sonnet-4.5' | 'anthropic/claude-opus-4.5' | 'google/gemini-4-argon' | 'google/gemini-3.8-flash' | 'google/gemini-3.5-flash' | 'google/gemini-3.5-flash-lite' | 'google/gemini-3.1-pro-preview' | 'google/gemini-3.1-flash-lite' | 'google/gemini-2.5-flash-lite' | 'xai/grok-4.5' | 'zai/glm-5.2' | 'moonshotai/kimi-k3': Pin an LLM. Omit for Auto. Must be included in the workspace plan.
  - `effort` 'fast' | 'default' | 'high' | 'xhigh'
  - `name` string: Session name, new sessions only
  - `desktopAppId` string, uuid: An appId from list_desktop_apps. The Agent then works inside that desktop app for this turn.

## Response `200`

The Agent session result.

- object
  - `sessionId` string, required
  - `threadId` string, required
  - `runId` string, required
  - `status` 'running', required
  - `url` string, required

## Other responses

- `400`: Invalid JSON body.
- `401`: Authentication required.
- `402`: Insufficient compute unit balance or free message limit reached.
- `403`: The requested model is not included in the workspace plan.
- `404`: Session or attachment not found or not accessible.
- `409`: A turn is already in progress.
- `422`: Invalid input or desktop app unavailable.

## Changes

- **2026-10-20** `8bea1de4b828`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/krea/apis/krea-api/changes/agent/send-message/post.md)

---

[API](https://skmtc.dev/krea/apis/krea-api.md) · [All operations](https://skmtc.dev/krea/apis/krea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/krea/apis/krea-api/revisions/f503def6ccba?raw)