API reference
Meta Tools
Generated HTTP reference for the 1 operation the published OpenAPI document describes under meta-tools.
1 min read
Meta Tools
This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.
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
Request body
Type: object | object
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
400 | object | object | Either the body matched neither accepted shape, or it was a valid intent for an operation no tool ships yet. The two are different bodies: the first carries issues, the second carries detail. |
424 | object | The intent is understood and nothing can serve it. Read the code: eligibility_empty is fixed by connecting a provider, direction_blocked is not. |
501 | object | A free-form description was sent to a deployment with no extractor wired. Send \{ intent: \{ ... \} \} instead; the structured path is always available. |
502 | object | The extractor ran and produced no usable intent, or failed. Rephrasing may work; sending a structured intent always does. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
alternatives | array of object | yes | The other eligible routes, score-descending, with the recommended one removed. Empty when only one route was eligible. |
recommended | object | yes | — |
resolved_intent | object | yes | The structured intent the lookup actually ran on. Echoed verbatim for the structured caller; for the natural-language caller it is how the description was read. |
Example response
{
"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,
"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": {}
}
}Example request
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": {}
}
}'