POST /v1/discover
Find the right tool for a task in a few words, best first, with a verdict; or every enabled tool with the jobs they serve. Free.
POST https://api.parel.si/v1/discover
Any valid key. Free.
Request
| Field | Type | Required | Description |
|---|---|---|---|
query | string | no | What you need, in a few words: "work email of a person", "competitor ads", "who is hiring", "youtube transcript". The words are matched one by one, so their order does not matter. Without it, every enabled tool. |
job | string | no | A job id from jobs[] ("work_email", "instagram"): only that job's tools. With query, the best of that job. |
limit | integer | no | How many tools a query returns, 1 to 50. Default 8. |
curl https://api.parel.si/v1/discover \
-H "Authorization: Bearer $PAREL_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"work email of a person"}'
How a query is matched
Each word of the query is scored on its own, by where it appears in a tool and how rare it is across all tools. A tool's name, its title and the other words people use for it count most; then its one-line summary, when to pick it over a look-alike, and what it returns; then its job; then its example prompt and description. Plurals and tenses are folded together ("emails", "email"), a few synonyms are read as one word ("twitter" and "x", "hiring" and "vacancies"), and some Hinglish works ("kisi company ka email", "naukri dhundo"). A tool named exactly (find_email) comes first.
Response
ok: true and tools[]. Disabled tools are never listed.
With a query: at most limit tools, best first, plus:
| Field | Type | Description |
|---|---|---|
query | string | The query as received |
verdict | string | match: the first tool fits. nearest: only something close was found; check before running. none: nothing fits, and tools is empty |
hint | string | On nearest and none: how to ask differently |
jobs | array | On none: the jobs, to browse with job instead |
Without a query: every enabled tool (or every tool of job), as before, plus jobs[]: each job's job id, label, tools (how many) and examples (up to three names).
Each row of tools[]:
| Field | Type | Description |
|---|---|---|
name | string | The tool name to send to POST /v1/run |
summary | string | One line |
description | string | The paragraph an agent reads: what it returns, what it will not do, which sibling to use, what drives the cost, India notes, then today's price and the ₹0 rule |
price | string | The price in a sentence, computed at today's rate: "~₹2.80 per successful result; a miss is free" |
estimated_cost_paise, estimated_cost | integer, string | The estimated charge for one call at today's rate; for a tool priced per result or by mode, its dearest case |
async | boolean | A slow job |
free_when_no_result | boolean | An empty answer is ₹0 |
confirm_required | boolean | Running it needs confirm: true whatever the input |
job | string | The job the tool serves (work_email); null for a tool not yet given one |
pick_when | string | Only on look-alike tools: when to pick this one, and which sibling serves the other needs |
score | number | With a query: how well it matched. Only the order means anything |
The price is computed by the same formula and exchange rate that settle the call. For the input schema, notes and an example input, read GET /v1/tools/:id. An unknown job answers 400 with error: "unknown_job" and the list of jobs, for ₹0.
Computed in-process from the seeded catalogue on 2026-11-17 with {"query": "work email of a person"}, the first two rows shown, descriptions shortened here:
{
"ok": true,
"query": "work email of a person",
"verdict": "match",
"tools": [
{
"name": "find_email",
"summary": "One person's work email from name + company domain, with confidence; a miss is free.",
"description": "One person's work email from their name and company: give domain (preferred) or company, plus full_name or first_name and last_name; or linkedin_handle alone. Returns the best-guess address with a confidence score (0 to…",
"price": "~₹2.77 per successful result; a miss is free",
"estimated_cost_paise": 277,
"estimated_cost": "₹2.77",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"job": "work_email",
"pick_when": "One known person at one company. Everyone at a company: domain_search; the format only: get_email_pattern.",
"score": 41.19
},
{
"name": "enrich_person",
"summary": "One known person from a work email, LinkedIn URL or name and company: title, employer, seniority, location, career history.",
"description": "One known person from a linkedin_url, a work email, or a name with an employer: data.person with name, title, headline, seniority, functions, city and country, employment_history[] and organization (name, domain, indust…",
"price": "~₹2.94 per successful result; a miss is free",
"estimated_cost_paise": 294,
"estimated_cost": "₹2.94",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"job": "person_profile",
"pick_when": "One known person from an email, profile link or name and company; LinkedIn's own profile: get_linkedin_profile.",
"score": 35.01
}
]
}
Related
GET /v1/tools: the same answers as aGET, withquery,jobandlimitas parameters.- Over MCP:
discover_tools, which with no query answers with the jobs instead of every tool, and puts the input schema in the first three rows of a match. MCP reference.
This page as Markdown: /docs/api/discover.md. Something wrong or missing: hello@parel.si.