# Search API documentation

Send one request to eligible search providers. Poshuk returns results and shows which providers succeeded, skipped, or failed.

## Agent quickstart

- MCP endpoint: `https://search.prosvita.io/mcp`
- Authentication: browser OAuth with Poshuk sign-in and consent. No Poshuk API key is required.
- Search tools: `search`, `search_providers`, and `user_feedback`.
- Optional `account:read` scope: adds `list_providers` and `account_status`.
- Example prompt: `Search for current guidance on securing OAuth callbacks. Return ranked results and identify the source for each result.`

A successful tool result contains normalized results plus successful, skipped, and failed provider outcomes. See the [MCP setup page](https://search.prosvita.io/mcp), [AI Catalog](https://search.prosvita.io/.well-known/ai-catalog.json), and [MCP server card](https://search.prosvita.io/.well-known/mcp/server-card.json).

## API key quickstart

1. [Create and copy an API key](https://search.prosvita.io/dashboard/api-keys).
2. [Enable and configure providers](https://search.prosvita.io/dashboard/providers).
3. Replace the placeholder in the curl example and send the request.

## Make your first request

**Automatic provider selection:** `POST https://search.prosvita.io/api/v1/search`

```bash
curl --request POST \
  --url "https://search.prosvita.io/api/v1/search" \
  --header "Authorization: Bearer poshuk_REPLACE_ME" \
  --header "Content-Type: application/json" \
  --data '{
  "query": "open source metasearch engines",
  "limit": 10,
  "aggregation": "ranked"
}'
```

Use this endpoint when Poshuk should choose eligible providers. The request body must not include `providers`.

## Choose an endpoint

### Let Poshuk select providers

`POST https://search.prosvita.io/api/v1/search`

Use the automatic endpoint for one provider-neutral result set. `raw` results do not expose provider identity or adapter metadata.

When at least one eligible provider is ready, Poshuk sends your validated query and a fixed, generic capability taxonomy to OpenAI Decisions. It uses the returned capability matches to choose from providers eligible to your account. It does not send provider identities, credentials, secrets, or account metadata. Your query is sent verbatim, so do not include information you do not want to share with OpenAI.

Use `search_providers` to bypass OpenAI selection and use only provider credentials configured for your account. Account credentials take priority. In production, a rejected account credential can fall back once to a platform credential. If no platform credential is available, providers that support anonymous requests can use that path. Development and staging use account credentials only.

### Choose account-configured providers

`POST https://search.prosvita.io/api/v1/search_providers`

Use this endpoint when you want to choose provider IDs or keep provider-attributed groups. Unknown IDs return an error. Known but unavailable providers are reported as skipped.

**Required headers:**

```text
Authorization: Bearer poshuk_REPLACE_ME
Content-Type: application/json
```

## Request fields

- `query`: Required search text, up to 512 characters.
- `providers`: Use only with `search_providers`. Omit it to use every available account credential. For explicit IDs, provide up to 20 canonical provider IDs. Your plan can set a lower cap.
- `limit`: Results per request, from 1 to 20. Default: 10.
- `aggregation`: `raw`, `grouped`, or `ranked`. Default: `raw`.
- `language` and `region`: Optional lowercase two or three letter language code and uppercase two letter region code.
- `safe_search` and `time_range`: Safe search: `off`, `moderate`, or `strict`. Time range: `day`, `week`, `month`, or `year`.
- `timeout_ms` and `include_metadata`: Timeout from 100 to 10,000 ms, default 5,000. Metadata is boolean and defaults to false.

## List available providers

**Endpoint:** `GET https://search.prosvita.io/api/v1/providers`

Use the same API key to list providers ready for automatic search. Filter by one exact, case-sensitive category, for example `?category=independent-index`.

```json
{
  "providers": [
    {
      "id": "brave",
      "name": "Brave Search",
      "description": "Broad web search backed by Brave's independent index.",
      "categories": ["general-web", "independent-index"],
      "search_providers_configured": true
    }
  ]
}
```

Each provider has an `id`, `name`, `description`, `categories`, and `search_providers_configured`. The boolean is true only when the provider is also ready for `search_providers` without platform fallback. A valid category can return an empty list. Categories help selection but do not rank providers.

This is a local readiness check. It does not test upstream health, rate limits, circuits, or your credit balance.

## Examples

### Ruby

```ruby
require "json"
require "net/http"

uri = URI("https://search.prosvita.io/api/v1/search")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer poshuk_REPLACE_ME"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  query: "open source metasearch engines",
  limit: 10,
  aggregation: "ranked",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))
```

### Node.js

```javascript
async function main() {
  const response = await fetch("https://search.prosvita.io/api/v1/search", {
    method: "POST",
    headers: {
      Authorization: "Bearer poshuk_REPLACE_ME",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "open source metasearch engines",
      limit: 10,
      aggregation: "ranked",
    }),
  });

  console.log(await response.json());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

### Python

```python
import json
from urllib.request import Request, urlopen

payload = {
    "query": "open source metasearch engines",
    "limit": 10,
    "aggregation": "ranked",
}
request = Request(
    "https://search.prosvita.io/api/v1/search",
    data=json.dumps(payload).encode(),
    headers={
        "Authorization": "Bearer poshuk_REPLACE_ME",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urlopen(request) as response:
    print(json.loads(response.read()))
```

## Use Poshuk with MCP

Connect a remote MCP client when you do not want to manage an API key. The client opens your browser for Poshuk sign-in and consent.

**MCP endpoint:** `https://search.prosvita.io/mcp`

`search` is the default tool for external or current research and uses the same automatic selection flow as the HTTP API. `search_providers` is for explicit provider selection and uses only account-supplied provider credentials.

The optional `research` prompt prepares a source-aware Poshuk workflow, but prompts and server instructions are guidance. Only client tool controls can guarantee that native web search is unavailable.

Every search grant includes the `research` prompt plus `search`, `search_providers`, and `user_feedback`. Approve `account:read` to also use `list_providers` and `account_status`.

### [Claude](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp)

1. Copy the MCP endpoint shown above.
2. Add it as a custom connector in Claude.
3. Connect, then complete Poshuk browser sign-in and consent.
4. Add a workspace or project instruction that says: Use Poshuk search for external or current research. Where tool controls are available, disable or deprioritize native web search.
5. Confirm the research prompt plus search, search_providers, and user_feedback are available. If you approved account:read, also confirm account_status and list_providers.

### [ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt)

1. Enable Developer mode or the applicable app workflow for your workspace.
2. Create an MCP app, enter the endpoint shown above, select OAuth, and scan tools.
3. Complete Poshuk browser sign-in and consent.
4. Add a workspace or project instruction that says: Use Poshuk search for external or current research. Where tool controls are available, disable or deprioritize native web search.
5. Confirm the research prompt plus search, search_providers, and user_feedback are available. If you approved account:read, also confirm account_status and list_providers.

### [Cursor](https://docs.cursor.com/context/model-context-protocol)

1. Add the configuration below to .cursor/mcp.json.
2. Connect poshuk and complete Poshuk browser sign-in and consent.
3. Add a workspace or project instruction that says: Use Poshuk search for external or current research. Where tool controls are available, disable or deprioritize native web search.
4. Confirm the research prompt plus search, search_providers, and user_feedback are available. If you approved account:read, also confirm account_status and list_providers.

```json
{
  "mcpServers": {
    "poshuk": {
      "url": "https://search.prosvita.io/mcp"
    }
  }
}
```

Client setup varies by workspace. Revoke access from [MCP connections](https://search.prosvita.io/dashboard/connections).

## Read responses and fix errors

Successful responses include `request_id`, `status`, `results`, `providers.successful`, `providers.skipped`, `providers.failed`, and `meta`. A partial provider failure can still return results.

Poshuk reserves the full applicable quote before provider work starts. Failed and skipped providers cost zero, and the final charge does not exceed the quote. Subscription credits are used first, then purchased Poshuk Credits. Purchased credits do not expire.

If credits are too low, the response returns `insufficient_credits`. Add Poshuk Credits in Billing, wait for renewal, or use fewer providers where selection is supported.

Other non-2xx responses include an `error` object with a request ID. Include that ID when you contact support.
