---
title: "Invoke one of the agent's tools directly"
method: POST
path: "/api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke"
tags: ["Tools"]
---

# Invoke one of the agent's tools directly

`POST /api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke`

## Request

- Base URL: `https://davinci-app.com`
- URL: `https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/tools/invoke`
- Auth: HTTP bearer

Runs a single tool and returns its result, with no model in the loop. Faster and
deterministic where the agent is neither, and it incurs no LLM charges.

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.

## Request body

- InvokeToolRequest
  - `toolbox` string, required: Toolbox holding the tool, for example `Core`.
  - `tool` string, required
  - `params` object: Arguments for the tool. Validated by the tool, not here.

## Response `200`

The tool ran and returned a result.

- InvokeToolResponse
  - `sessionId` string, uuid, required
  - `toolbox` string, required
  - `tool` string, required
  - `isError` boolean, required: Always false here — a tool that reported an error is answered as `422`, so a `200` means the tool succeeded.
  - `content` ToolResultContent, required
    - `text` string, required: Every text part the tool returned, joined by newlines.
    - `parts` object[], required: Non-text parts, such as images, passed through with their `type` intact.
  - `structuredContent` object: Present when the tool returns structured output as well as text.

## Other responses

- `400`: Invalid request. Error code is `MISSING_TOOL_TARGET`, `INVALID_TOOL_TARGET`, or `INVALID_PARAMS`.
- `401`: No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request.
- `403`: Authenticated but not authorized. Either the acting user lacks the required resource permission, the key's scope ceiling excludes it, or the endpoint rejects this credential type (`CREDENTIAL_NOT_PERMITTED`).
- `404`: No such session, it belongs to another user, it belongs to a different project than the one in the path (`SESSION_NOT_FOUND`), or no such toolbox for this session.
- `409`: The project this session opened is no longer running. Error code is `PROJECT_NOT_RUNNING`.
- `422`: The tool ran and refused: bad arguments, a precondition it needs, or a permission your credential does not hold. Error code is `TOOL_ERROR` and the message is the tool's own.
- `429`: Request rate exceeded, either globally or for this key.
- `500`: Unexpected server error.

## Changes

- **2026-09-15** (v2) `67c8b8616dbb`: 8 info
  - the `success` response property const value `false` was added for the status `400`
  - the `success` response property const value `false` was added for the status `401`
  - the `success` response property const value `false` was added for the status `403`
  - the `success` response property const value `false` was added for the status `404`
  - …4 more
- **2026-09-15** (v2) `48948af37797`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/projects/:projectId/sessions/:sessionId/tools/invoke/post.md)

---

[API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)