Skip to content
Poshuk
Menu

Search API documentation

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

Make your first request

POST

Automatic provider selection

POST https://search.prosvita.io/api/v1/search
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

POST

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.

What happens: 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.

What 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.

Need direct control? Use search_providers. It bypasses OpenAI selection and uses 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

Authorization: Bearer poshuk_REPLACE_ME
Content-Type: application/json

Request fields

JSON
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

GET
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.

{
  "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

standard library

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

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

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

remote 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

  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

  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

  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.
{
  "mcpServers": {
    "poshuk": {
      "url": "https://search.prosvita.io/mcp"
    }
  }
}

Client setup varies by workspace. Revoke access from MCP connections.

Read responses and fix errors

JSON

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.