curl --request POST \
--url https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"toolbox": "<string>",
"tool": "<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:
result = session.invoke_tool(
toolbox="Core",
tool="ReadObject",
params={"objectId": object_id},
)
print(result.content.text)
import { DavinciClient } from '@celedon/davinci-sdk';
const client = new DavinciClient({
apiKey: process.env.DAVINCI_API_KEY!,
});
await client.sessions.with(projectId, async (session) => {
const result = await session.invokeTool({
toolbox: 'Core',
tool: 'ReadObject',
params: { objectId },
});
console.log(result.content.text);
});
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({toolbox: '<string>', tool: '<string>'})
};
fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"toolbox": "<string>",
"tool": "<string>",
"isError": true,
"content": {
"text": "<string>",
"parts": [
{}
]
},
"structuredContent": {}
}{
"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": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Invoke one of the agent's tools directly
Runs a single tool and returns its result, with no model in the loop. Faster and deterministic where the agent is neither, and it spends no LLM credits.
This needs a session because a tool belongs to one: the tools available are the ones the session’s project has open, and the tool acts on that project’s live state.
A tool that refuses answers 422 with the tool’s own message. Permission
refusals are deliberately indistinguishable from “no such tool” — a key cannot
use the error to discover what it is not allowed to do.
curl --request POST \
--url https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"toolbox": "<string>",
"tool": "<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:
result = session.invoke_tool(
toolbox="Core",
tool="ReadObject",
params={"objectId": object_id},
)
print(result.content.text)
import { DavinciClient } from '@celedon/davinci-sdk';
const client = new DavinciClient({
apiKey: process.env.DAVINCI_API_KEY!,
});
await client.sessions.with(projectId, async (session) => {
const result = await session.invokeTool({
toolbox: 'Core',
tool: 'ReadObject',
params: { objectId },
});
console.log(result.content.text);
});
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({toolbox: '<string>', tool: '<string>'})
};
fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"toolbox": "<string>",
"tool": "<string>",
"isError": true,
"content": {
"text": "<string>",
"parts": [
{}
]
},
"structuredContent": {}
}{
"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": {}
}
}{
"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
Response
The tool ran and returned a result.
Always false here — a tool that reported an error is answered as 422, so a
200 means the tool succeeded.
Present when the tool returns structured output as well as text.