Meta Tools

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

Every operation below requires a Bearer token. See Authentication.

POST /v1/meta-tools/discover

Ask which route to take for an intent, and why

A planning surface, and never a required step: an agent that already knows which tool it wants calls that tool directly. Read-only in the contract sense — it dispatches no payment and writes no audit entry.

TWO WAYS IN, ONE RANKING. Send { intent: { ... } } and the lookup is deterministic and free. Send { description: "..." } and the description is first turned into that same structured intent, which requires the managed tier; a deployment without the extractor answers 501 rather than guessing. Either way the resolved intent is echoed back in resolved_intent, which is how the natural-language caller sees what its sentence was read as.

recommended IS A RANKING, NOT A RESERVATION. The router runs again at execution time and may pick a different provider if telemetry has moved, which is why provider_id is published for transparency and is not a value the agent passes back. alternatives holds the other eligible routes in score-descending order, with the recommended one removed — so it is empty when only one route was eligible, and that emptiness is not a failure.

args_template is a starting point, not a complete call: it carries forward the fields the intent already supplied. The recipient and anything else the tool requires are the agent's to fill.

ONE REPAIR RUNS BEHIND THE 424, at most once every thirty seconds per project. When nothing is eligible, the most common cause is a per-tenant eligibility set that was never refreshed rather than a genuinely unconfigured project, so the endpoint re-seeds it idempotently and retries the lookup exactly once before answering. The retry can only surface what the refreshed catalog honestly allows. A second call inside the window skips the repair and answers from what is already there, so a client that polls on a 424 will not make it heal faster.

THE TWO 424 CODES MEAN DIFFERENT THINGS AND THE DIFFERENCE IS ACTIONABLE. eligibility_empty means nothing is configured for this combination and connecting a provider is the fix. direction_blocked means candidates exist but every one of them moves money the wrong way for this operation — connecting another provider does not fix it, because the rail itself does not pay out here.

Request body

Type: object | object

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/meta-tools/discover \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "intent": {
         "operation": "charge",
         "amount_minor": 1000,
         "currency": "BRL",
         "country": "string",
         "urgency": "instant",
         "recipient_kind": "cnpj",
         "metadata": {}
       }
     }'

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

{
  "intent": {
    "operation": "charge",
    "amount_minor": 1000,
    "currency": "BRL",
    "country": "string",
    "urgency": "instant",
    "recipient_kind": "cnpj",
    "metadata": {}
  }
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/meta-tools/discover",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "intent": {
        "operation": "charge",
        "amount_minor": 1000,
        "currency": "BRL",
        "country": "string",
        "urgency": "instant",
        "recipient_kind": "cnpj",
        "metadata": {}
      }
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meta-tools/discover", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "intent": {
      "operation": "charge",
      "amount_minor": 1000,
      "currency": "BRL",
      "country": "string",
      "urgency": "instant",
      "recipient_kind": "cnpj",
      "metadata": {}
    }
  }),
});

const data = await res.json();

const result = await cs.api.post("/v1/meta-tools/discover", {
  body: {
    intent: {
      operation: "charge",
      amount_minor: 1000,
      currency: "BRL",
      country: "string",
      urgency: "instant",
      recipient_kind: "cnpj",
      metadata: {}
    }
  }
});

{
  "recommended": {
    "tool": "string",
    "rail": "string",
    "provider_id": "provider_0000000000000000",
    "args_template": {},
    "reasons": [
      "string"
    ]
  },
  "alternatives": [
    {
      "tool": "string",
      "rail": "string",
      "provider_id": "provider_0000000000000000",
      "cost_minor": 1,
      "mean_latency_ms": 0,
      "latency_p50_ms": 0,
      "success_rate": 0,
      "reasons": [
        "string"
      ]
    }
  ],
  "resolved_intent": {
    "operation": "charge",
    "amount_minor": 1000,
    "currency": "BRL",
    "country": "string",
    "urgency": "instant",
    "recipient_kind": "cnpj",
    "metadata": {}
  }
}