GET
/
v1
/
teams
/
{teamId}
/
agent-tools
/
{toolId}
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.agentTools.getAgentTool({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  toolId: process.env.OCTOSPARK_TOOL_ID ?? "toolId",
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "currentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": 123,
  "description": "<string>",
  "inputSchema": {},
  "outputSchema": {},
  "executor": {
    "type": "http",
    "url": "<string>",
    "headers": {},
    "secretHeaderName": "<string>"
  },
  "hasSecret": true,
  "requiresApproval": true,
  "timeoutMs": 30500,
  "createdBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

​
toolId
string
required

Custom agent tool id (UUID), as returned by the list/create agent tools endpoints.

Response

AgentCustomTool

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
name
string
required

Tool name, unique within the team: 1-64 characters of a-z, 0-9 and underscore. The model sees it as custom__; tool policies address it as custom. or the custom capability.

Pattern: ^[a-z0-9_]{1,64}$
​
currentVersionId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
version
integer
required

The current version number.

​
description
string
required

What the tool does and when to use it; shown to the model (1-1024 characters).

Required string length: 1 - 1024
​
inputSchema
object
required

JSON Schema (draft 2020-12 subset) with type "object" describing the arguments. Calls whose arguments do not validate are rejected before the request is made. At most 16 KiB.

​
outputSchema
object
required

Optional JSON Schema the parsed JSON response must satisfy; a non-conforming response is reported to the model as a tool failure. null for no check.

​
executor
object
required

How the tool is called: an http request (GET or POST) to an https endpoint, with optional static headers and an optional stored secret. Agent calls send an Idempotency-Key header that stays the same if the run retries the same call; make POST endpoints honour it to avoid duplicate side effects.

​
hasSecret
boolean
required

Whether an encrypted secret is stored for this version. The secret itself is never returned.

​
requiresApproval
boolean
required

When true every call needs human approval before it executes. Until an approval handler is wired the call is refused ("needs approval; approval flow not yet available") and never executes. The admin test endpoint is not gated.

​
timeoutMs
integer
required

Per-call timeout in milliseconds (1000-60000).

Required range: 1000 <= x <= 60000
​
createdBy
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
createdAt
string
required

When the tool was created (ISO-8601 UTC).

​
updatedAt
string
required

When the tool last changed (ISO-8601 UTC).