Skip to main content
POST
cURL

Authorizations

Authorization
string
header
default:dav_ak_live_your_token
required

Personal access token. The scopes granted at issuance determine both which operations the key may call and the ceiling on the resource permissions it can exercise. Each scope family is a ladder: projects:manage implies projects:write and projects:read; cards:manage implies cards:write and cards:read; and teams:manage implies teams:write and teams:read. These are named API capability bundles, not blanket domain roles: manage exposes only the permissions enumerated for that scope and never bypasses the acting user's current role-based access.

Path Parameters

projectId
string
required

Project id. May be compound in the form {projectId}--{branchName}.

Minimum string length: 1
sessionId
string<uuid>
required

Session id from createSession.

Body

application/json
message
string
required

What you want the agent to do.

Required string length: 1 - 100000
messageId
string

Your own id for this prompt, echoed back and recorded in the transcript. Generated for you if omitted.

context
object

Opaque data kept with the session and returned to your webhook alongside the agent's replies. Davinci does not interpret it.

model
string

A model key returned by listAgentModels. Omit it to use the calling account's default model. The choice applies to this prompt; every prompt that omits it uses the account default.

Required string length: 1 - 200
Pattern: ^[a-z0-9][a-z0-9._:-]*$
modelOptions
object

Model configuration keyed by the option keys returned for the selected model by listAgentModels. Values may be strings, numbers, or booleans. Omitted options use that model's effective account defaults.

Whether the agent may use web search for this prompt.

persona
string

The id of a persona the project defines, which sets who the agent is for this prompt and every one after it in the session. Omit to keep whichever persona the session is already running under; omitting it on the first prompt uses the project's default.

This is an id, not a persona. An object is refused with INVALID_PERSONA, because a persona's name, purpose and approach are written into the system prompt — accepting one here would let a caller rewrite the instructions that decide what the agent will refuse to do. Define personas in the project, then name one.

An id the project does not define is refused with UNKNOWN_PERSONA rather than quietly falling back to a default.

Maximum string length: 200

Response

The agent accepted the prompt. The run is now in progress.

sessionId
string<uuid>
required
taskId
string
required

The run the prompt joined.

messageId
string
required
status
string
required

Always message_delivered — a refusal is a 409, not a status here.