Docs
OverviewGuidesZero & MCPAPI referenceChangelog
Search

Search

Search leads (name, email, company), companies (name, domain), campaigns (name) and calls (the lead's name or email, the number, the summary) at once, newest first, at most `limit` of each kind. API keys see the kinds their scopes can read (`sequences:read`, `calls:read`).

API key access

Needs the leads:read scope with an API key (ro_pat_...). A signed-in session uses the caller's role.
GET/api/v1/search

Authorization

AuthorizationBearer <token>

Access token from /api/v1/auth/login, or an API key (ro_pat_..., RO-176) from /api/v1/workspaces/current/api-keys: the key implies its workspace and needs the route's scope. MCP connectors (/api/v1/mcp only) may use an OAuth access token (ro_oat_..., RO-284).

In: header

Query Parameters

qstring

Text to look for (case-insensitive substring)

Length1 <= length <= 200
limit?integer

Per kind; default 5

Formatint64
Range1 <= value <= 20

Header Parameters

X-Workspace-Id?string | null

Id of the workspace to act on (must be a member).

Response Body

curl -X GET "http://localhost:8000/api/v1/search?q=string&limit=1" \  -H "X-Workspace-Id: string"
{
  "q": "string",
  "items": [
    {
      "kind": "lead",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "title": "string",
      "subtitle": "string"
    }
  ]
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Run Research

Research the lead and its company now; store the result and add a `research_completed` event to the timeline. Without an `icp` in the body, fit is scored against the workspace ICP from `/workspaces/current/profile` (generic B2B fit if that is empty too). 404 for a missing lead, 422 when no source could be gathered, 502 when the model call fails. With `RESEARCH_ASYNC=true` (off by default) the lead is checked (404), the research is queued as a background job and the response is 202 with the job; poll `GET /leads/{id}/research/jobs/{job_id}` and read the result with `/research/latest`. A repeated request while that job is queued or running returns it.

Activate Sequence

`draft`/`paused` -> `active`. 409 without steps or a subject on the first email. A sequence with email steps also needs the workspace's postal address (CAN-SPAM): without it, 409 with `detail: {"code": "missing_postal_address", "message": ...}`.