Tools

1 operation under /v1/tools/search (POST): parameters, status codes, refusal bodies, and the same request in curl, HTTP, Python and TypeScript.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

POST `/v1/tools/search`

POSThttps://api.codespar.dev/v1/tools/search

Find tools by intent, in words

Describe what you want to do and receive the tools that serve it, with a confidence and the reason for each one.

This route does not fail because of the classifier. When the model key is not configured, or the call to the classifier goes wrong, it DEGRADES to a heuristic search and answers 200 anyway, and it says which path it used in source. A caller that treats source: "fallback" as silent success is reading a weaker result without knowing it; the field exists so that this is visible.

The ceiling on limit is 5.

Request body

Field	Type	Required	Description
`intent`	`string`	yes	What you want to do, in words.
`limit`	`integer`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	The body did not match the schema.

Response 200

Field	Type	Required	Description
`elapsed_ms`	`integer`	yes	—
`hits`	array of object	yes	—
`intent`	`string`	yes	Echoes what was requested.
`source`	`"llm"` \| `"fallback"`	yes	`llm` when the classifier answered; `fallback` when the heuristic search answered in its place.

Example request

curl -X POST https://api.codespar.dev/v1/tools/search \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "intent": "string",
       "limit": 1000
     }'

POST /v1/tools/search HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "intent": "string",
  "limit": 1000
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/tools/search",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "intent": "string",
      "limit": 1000
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/tools/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "intent": "string",
    "limit": 1000
  }),
});

const data = await res.json();

const result = await cs.api.post("/v1/tools/search", {
  body: {
    intent: "string",
    limit: 1000
  }
});

Example response 200

application/json

{
  "intent": "string",
  "hits": [
    {
      "tool_name": "Example",
      "confidence": "high",
      "rationale": "string"
    }
  ],
  "elapsed_ms": 0,
  "source": "llm"
}

POST /v1/tools/search

On this page

POST `/v1/tools/search`