Auth: required. Send an ivy_ API key (Authorization: Bearer ivy_… or X-Ivy-Api-Key), a Clerk session JWT (Authorization: Bearer …) or the Clerk __session cookie (browser sessions). See Authentication.

Submit a user message and receive the agent's response.

Streaming mode (stream: true, default): response is a Server-Sent Events stream. Each line is data: <JSON> where the JSON is one stream event. The stream terminates with a sync.completed event.

Batch mode (stream: false): response is a JSON object with events (array of all stream events) and the final state.

clientIdstring

Client identifier for version vector tracking

streamboolean

Stream response via SSE (true, default) or collect into a JSON batch (false)

Responses

`200` OK

Turn executed — SSE stream or JSON batch

Response shape:

successboolean

eventsobject[]

stateobject

Full session state snapshot persisted in Supabase

curl -X POST 'https://ivybiosciences.com/api/v1/sessions/{sessionId}/execute' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "content": ""
}'

POST /v1/sessions/{sessionId}/execute

Request

Path parameters

Request body

Responses

`200` OK

`400` Bad Request

`401` Unauthorized

`404` Not Found