Discover
POST /v1/discover ranks the whole catalog for a job described in plain words, with price, health and hints. Free.
POST /v1/discover
content-type: application/jsonBody
| Field | Type | Required | Default | Meaning |
|---|---|---|---|---|
query | string | yes | The job, in plain words. 1–500 characters. | |
category | string | no | Only tools in this category, by id: web-search, weather, research… (all categories) | |
limit | integer | no | 8 | How many candidates, 1–25 |
include_unavailable | boolean | no | false | Also list tools that are not configured on this server |
curl -s -X POST https://api.useakashi.xyz/v1/discover \
-H 'content-type: application/json' \
-d '{"query": "weather in Lagos", "category": "weather", "limit": 2}'Response
{
"query": "weather in Lagos",
"count": 2,
"candidates": [
{
"id": "openweather/current",
"provider": "openweather",
"providerName": "OpenWeather",
"slug": "current",
"displayName": "OpenWeather Current Weather",
"summary": "Weather right now for a city or coordinates: temperature, feels-like, humidity, wind, rain, sunrise.",
"categories": ["weather"],
"render": "weather",
"price": { "usd": "0.005", "atomic": "5000", "tier": "standard", "network": "eip155:84532" },
"method": "POST",
"path": "/v1/run/openweather/current",
"available": true,
"score": 1.0,
"health": { "status": "healthy", "runs": 42, "successRate": 1.0, "p50Ms": 410, "p95Ms": 980, "lastOkAt": 1791374400 }
},
{ "id": "akashi/weather", "…": "…" }
],
"hints": [
"POST /v1/inspect with {\"id\": \"openweather/current\"} for its input schema, then POST /v1/run/openweather/current.",
"Related: openweather/forecast",
"Related: openweather/air-quality",
"Related: openweather/geocode"
]
}| Field | Meaning |
|---|---|
count | How many candidates were returned |
candidates[].id | The tool id to inspect and run |
candidates[].price | {usd, atomic, tier, network} per call |
candidates[].path | Where to run it: POST this path |
candidates[].available | false if the tool is not configured on this server (only listed with include_unavailable) |
candidates[].score | Relevance, relative to the best match (1.0) |
candidates[].health | Akashi's record of this tool's recent runs (below) |
hints | What to call next, a cheaper tool for the same kind of job if there is one, and related tools. When nothing matches, a suggestion to rephrase. |
Health
Health comes from Akashi's own recent runs of each tool (up to the last 200). The first row that applies wins:
health.status | Meaning |
|---|---|
outage | The 5 most recent runs all failed |
degraded | Fewer than 80% of recent runs succeeded |
healthy | A run succeeded in the last 15 minutes |
stable | At least 20 runs, and 95% or more succeeded |
unknown | None of the above, for example no runs yet |
p50Ms and p95Ms are the median and 95th-percentile run times of successful runs, successRate is the share of runs that succeeded, and lastOkAt is the Unix time of the last success. A tool with no runs yet shows "status": "unknown" and null figures.
Ranking
Discover matches the query against each tool's name, summary, categories, provider and description, and expands common synonyms ("scrape" also matches "extract", "currency" matches "fx"). Ties on relevance go to the healthier, then the cheaper tool. Use health to break ties, not to filter: a tool marked unknown may simply be new.