curl --request POST \
--url https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "<string>"
}
'import os
from davinci_sdk import DavinciClient
with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
with client.sessions.create(project_id) as session:
session.send_message(
"Add a 10mm M3 standoff under each corner of the base plate"
)
final = session.wait_until_done()
print(final.status)
import { DavinciClient } from '@celedon/davinci-sdk';
const client = new DavinciClient({
apiKey: process.env.DAVINCI_API_KEY!,
});
await client.sessions.with(projectId, async (session) => {
await session.sendMessage('Add a 10mm M3 standoff under each corner of the base plate');
const final = await session.waitUntilDone();
console.log(final.status);
});
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({message: '<string>'})
};
fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"taskId": "<string>",
"messageId": "<string>",
"status": "<string>"
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Send a prompt to the session's agent
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 spends credits doing it, which
is why this needs the agent:message scope rather than a project write.
curl --request POST \
--url https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "<string>"
}
'import os
from davinci_sdk import DavinciClient
with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
with client.sessions.create(project_id) as session:
session.send_message(
"Add a 10mm M3 standoff under each corner of the base plate"
)
final = session.wait_until_done()
print(final.status)
import { DavinciClient } from '@celedon/davinci-sdk';
const client = new DavinciClient({
apiKey: process.env.DAVINCI_API_KEY!,
});
await client.sessions.with(projectId, async (session) => {
await session.sendMessage('Add a 10mm M3 standoff under each corner of the base plate');
const final = await session.waitUntilDone();
console.log(final.status);
});
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({message: '<string>'})
};
fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"taskId": "<string>",
"messageId": "<string>",
"status": "<string>"
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Authorizations
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
Project id. May be compound in the form {projectId}--{branchName}.
1Session id from createSession.
Body
What you want the agent to do.
1 - 100000Your own id for this prompt, echoed back and recorded in the transcript. Generated for you if omitted.
Opaque data kept with the session and returned to your webhook alongside the agent's replies. Davinci does not interpret it.
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.
1 - 200^[a-z0-9][a-z0-9._:-]*$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.
Hide child attributes
Hide child attributes
A typed model option value.
Whether the agent may use web search for this prompt.
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.
200