CEceledon-solutions
Sessions

Send a prompt to the session's agent

Changed on

Gives the agent something to do. Starts a run if none is going, and adds a turn to the conversation if one is.

This returns as soon as the agent has accepted the prompt, not when it has finished — a run takes as long as the work takes. Follow it with getSession and read agent.status, or let the SDK's waitUntilDone do that for you.

Acceptance is not the same as success. A 202 means the agent took the prompt; a 409 means it refused, which happens when the run it belonged to has ended. Recreate the session in that case rather than retrying the message.

The agent can change anything in the project and is charged for AI usage doing it, which is why this needs the agent:message scope rather than a project write.

post/api/v2/projects/{projectId}/sessions/{sessionId}/messages

Request

  • Base URL
    https://davinci-app.com
  • Auth
    HTTP bearer

Request body

messagestring required

What you want the agent to do.

messageIdstring

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

contextobject

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

modelstring

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.

modelOptionsobject

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.

webSearchboolean

Whether the agent may use web search for this prompt.

personastring

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.

Response

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

sessionIdstring uuid required
taskIdstring required

The run the prompt joined.

messageIdstring required
statusstring required

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

Changes

  • v267c8b8616dbbRevision changes
    • info

      the response property const value false was added for the status

    • info

      the response property const value false was added for the status

    • info

      the response property const value false was added for the status

    • info

      the response property const value false was added for the status

    • info

      the response property const value false was added for the status

    • info

      the response property const value false was added for the status

    • info

      the response property const value false was added for the status

  • v248948af37797Revision changes
    • info

      endpoint added