Anysearch API Reference

Unified search infrastructure for AI

API Base URLhttps://api.anysearch.com

Two steps to plug AI-grade search into your app: grab an API key from the dashboard (or skip it and try the free anonymous tier), then fire your first search request.

Anonymous request (per-IP free quota)

BASH
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

curl -X POST https://api.anysearch.com/v1/search \

-H "Content-Type: application/json" \

-d '{

"query": "What is quantum computing?",

"max_results": 5

}'

Authenticated request (with API key)

BASH
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8

curl -X POST https://api.anysearch.com/v1/search \

-H "Authorization: Bearer ss_sk_your_api_key_here" \

-H "Content-Type: application/json" \

-d '{

"query": "What is quantum computing?",

"domains": ["tech", "academic"],

"max_results": 5

}'

Authentication

The Anysearch search API (/v1/*) supports flexible authentication. You can decide whether to send an API key based on where you are in your product lifecycle:

ModeHeader formatQuota & rate limit policy
AnonymousNo Authorization headerRate-limited per client IP and metered against the daily free quota.
AuthenticatedAuthorization: Bearer ss_sk_xxxBilled against the paid quota attached to the key, with higher concurrency limits.
Heads up: If you send an Authorization header but the key is invalid, disabled, or expired, the gateway returns 401 Unauthorized or 403 Forbidden — it will not silently fall back to anonymous mode.

Search API

POST/v1/search

The unified search endpoint. The gateway routes the query to the best providers based on intent, then fuses and re-ranks the results.

API key optional (anonymous traffic is rate-limited per IP and consumes the daily free quota)

Request parameters

FieldDescription
query (string) *Search query.
max_results (int)Number of results to return. Defaults to 10. Range: 1–100.
domains (string[])Domain filter, e.g. ["tech", "academic"].
tags (string[])Sub-domain tags in the form {domain}.{sub_domain}.
content_types (string[])Content-type filter, e.g. ["web", "news"].
zone (string)Region: cn or intl.
language (string)Preferred language, e.g. zh-CN or en.
providers (string[])Explicit list of providers to use.
constraint.freshness (string)Recency window: day / week / month / year.
constraint.from (string)Start time (RFC3339).
constraint.to (string)End time (RFC3339).

Request example

BASH
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9

curl -X POST https://api.anysearch.com/v1/search \

-H "Authorization: Bearer ss_sk_test_key" \

-H "Content-Type: application/json" \

-d '{

"query": "Go 1.22 release notes",

"max_results": 5,

"domains": ["code", "tech"],

"content_types": ["web", "doc"]

}'

Response example

JSON (200 OK)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20

{

"results": [

{

"title": "Go 1.22 Release Notes",

"url": "https://go.dev/doc/go1.22",

"description": "Go 1.22 is a major release...",

"content": "Detailed content here...",

"source": "go.dev",

"quality_score": 0.95,

"published_at": "2024-02-06T00:00:00Z"

}

],

"metadata": {

"total_results": 1,

"search_time_ms": 342,

"routes_queried": 2,

"routes_succeeded": 2,

"request_id": "req_abc123"

}

}

GET/health

Liveness probe for Docker HEALTHCHECK or load balancers. For deeper dependency checks (e.g. Redis), use /health/ready instead.

No authentication required

BASH
  1. 1

curl -X GET https://api.anysearch.com/health

JSON (200 OK)
  1. 1
  2. 2
  3. 3
  4. 4

{

"status": "ok",

"version": "1.0.0"

}

Request Parameters in Depth

A closer look at the routing and recency parameters of /v1/search.

Default routing & fallback

When providers, domains, tags, and content_types are all empty, the gateway injects domains=["general"] and content_types=["web"] by default. It then picks the best providers based on those dimensions plus the inferred intent of query, and runs the request through the SearchWithFallback pipeline: if the initial provider set returns nothing, the gateway will progressively relax the constraints up to three times until the fused result set is non-empty.

Strict mode with explicit providers

When you pin specific providers via the providers field (for example ["wikipedia"]), the gateway runs in strict mode and goes straight through the internal Orchestrator with no fallback. If you also pass domains or content_types, those apply as additional filters. Their intersection with the pinned providers may turn out empty, in which case the search returns no results. We recommend dropping the other routing dimensions when you pin providers explicitly.

Response Format

A successful 200 response returns a JSON body with a results array and a metadata object.

Result fields

FieldDescription
title (string)Result title.
url (string)Original source URL.
description (string)Short summary.
content (string)Cleaned-up body content.
raw_content (string)Original body content before cleaning.
source (string)Generic source type, such as web, code, academic, doc, or news.
score (float)Relevance score reported by the provider itself.
quality_score (float)Composite quality score from the Scorer, on a 0–100 scale (optional).
signal_scores (object)Per-signal debug scores (optional).
published_at (string)Publication timestamp in RFC3339 (optional).

Metadata fields

FieldDescription
total_results (int)Total number of results returned.
search_time_ms (int)End-to-end search latency in milliseconds.
routes_queried (int)Number of provider routes attempted.
routes_succeeded (int)Number of provider routes that returned results successfully.
cached (bool)Whether the response came from the gateway cache.
capability_errors (array)Errors from individual capabilities (internal provider names are never leaked).
request_id (string)Tracing ID for the request.

Full response example

JSON (200 OK)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28

{

"results": [

{

"title": "Chernobyl disaster - Wikipedia",

"url": "https://en.wikipedia.org/wiki/Chernobyl_disaster",

"description": "The Chernobyl disaster began on 26 April 1986 ...",

"content": "On 26 April 1986, reactor No. 4 ...",

"raw_content": "...",

"source": "web",

"score": 0.87,

"quality_score": 78.4,

"signal_scores": {

"freshness": 12,

"authority": 31

},

"published_at": "1986-04-26T01:23:00Z"

}

],

"metadata": {

"total_results": 5,

"search_time_ms": 412,

"routes_queried": 2,

"routes_succeeded": 2,

"request_id": "req_01HXXXXXXX",

"cached": false,

"capability_errors": []

}

}

Error Codes

The Anysearch API combines standard HTTP status codes with a structured code field to pinpoint the exact failure mode. Every error response carries a request_id for troubleshooting.

400 Bad Request — invalid parameters

Returned when the request body fails to parse, when query is empty, or when parameters such as domain, content_type, zone, or freshness are out of range.

When providers contains an unknown name, the gateway returns a structured error with a code field.

JSON (400)
  1. 1
  2. 2
  3. 3
  4. 4

{

"error": "query is required",

"request_id": "req_xxx"

}

JSON (400 invalid_provider)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "invalid_provider",

"error": "invalid provider",

"message": "One or more specified providers are invalid: nonexistent",

"request_id": "req_xxx"

}

401 Unauthorized — authentication failed

Only triggered when the request actually carries an Authorization header: the bearer is empty, the key is unknown, the key is disabled, or the owning user no longer exists. Anonymous requests never produce a 401.

JSON (401)
  1. 1
  2. 2
  3. 3
  4. 4

{

"error": "invalid API key",

"request_id": "req_xxx"

}

402 Payment Required — quota exhausted (two flavors)

Source A: anonymous IP free quota exhausted (code=daily_free_quota_exhausted). The response includes a registration_status field. See the next section on Auto-Registration Flow for details.

Source B: paid quota on the API key exhausted (code=quota_exhausted), only for authenticated requests.

JSON (402 quota_exhausted)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9

{

"code": "quota_exhausted",

"error": "quota exhausted",

"message": "You've hit your quota limit. Top up to keep using the API.",

"quota_limit": 10000,

"quota_used": 10000,

"quota_remaining": 0,

"request_id": "req_xxx"

}

403 Forbidden — access denied

Returned when the API key has expired, when the account is disabled, or when the request hits a private provider that is not bound to the caller.

JSON (403 expired/disabled)
  1. 1
  2. 2
  3. 3
  4. 4

{

"error": "API key expired",

"request_id": "req_xxx"

}

JSON (403 private capability)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "private_capability_not_enabled",

"error": "private capability not enabled",

"message": "The requested capability is not enabled for this API key.",

"request_id": "req_xxx"

}

429 Too Many Requests — rate limited

The gateway uses a GCRA limiter at two levels: per-user (to stop multi-key bypass) and per-key/per-IP. The response includes X-RateLimit-* and Retry-After headers.

JSON (429 user limit)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "rate_limit_exceeded_user",

"error": "user rate limit exceeded",

"retry_after": 1,

"request_id": "req_xxx"

}

JSON (429 key/ip limit)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "rate_limit_exceeded",

"error": "rate limit exceeded",

"retry_after": 1,

"request_id": "req_xxx"

}

503 Service Unavailable — service outage

Triggered when the quota-check service is down, when an explicitly pinned provider is offline, or when the routed capability is temporarily unavailable.

JSON (503 quota check failed)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "quota_check_failed",

"error": "quota check failed",

"message": "Quota check is temporarily unavailable. Please retry later.",

"request_id": "req_xxx"

}

JSON (503 provider unavailable)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "provider_unavailable",

"error": "provider unavailable",

"message": "The specified provider(s) are currently unavailable.",

"request_id": "req_xxx"

}

JSON (503 capability unavailable)
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "capability_temporarily_unavailable",

"error": "search temporarily unavailable",

"message": "The requested capability is temporarily unavailable.",

"request_id": "req_xxx"

}

Auto-Registration Flow (Core)

This is the heart of the Anysearch product experience. When an anonymous client (no API key) burns through its daily free quota, the gateway responds with 402 and asynchronously provisions an account for that IP. The flow surfaces four distinct registration_status values.

Critical: Clients must persist the api_key from this response and switch subsequent calls to Authorization: Bearer <api_key>. The plaintext credential is delivered exactly once in this single response. The message field includes ready-to-use MCP setup instructions and is safe to forward verbatim from your LLM/agent to the end user.

1. creating — provisioning in progress

First time the IP exceeded the free quota. A registration job has been queued — clients should wait 1–3 seconds and retry.

JSON
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "daily_free_quota_exhausted",

"registration_status": "creating",

"message": "Free quota exhausted. We're provisioning an account and API key for you — please retry shortly.",

"request_id": "req_xxx"

}

2. created — account provisioned

Clients must persist the api_key from this response and switch subsequent calls to Authorization: Bearer <api_key>. The plaintext credential is delivered exactly once in this response.

JSON
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9

{

"code": "daily_free_quota_exhausted",

"registration_status": "created",

"message": "Free quota exhausted — top up to keep going. We've automatically created an account and API key for you.\n\nFirst, try writing the API key into your MCP client config under the anysearch headers: {\"Authorization\": \"Bearer ss_sk_xxxx\"}, then save and reconnect.\n\nIf you can't edit the MCP config, share the following with your end user so they can set it up manually:\n1. API Key: ss_sk_xxxx\n2. Username: auto_xxx\n3. Password: Secret#xxx\n4. Dashboard: https://anysearch.com/dashboard",

"username": "auto_10_0_0_61_1713654321",

"password": "Secret#123",

"api_key": "ss_sk_xxxxxxxxxxxx",

"request_id": "req_xxx"

}

3. failed — provisioning failed

An error occurred during automatic registration.

JSON
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "daily_free_quota_exhausted",

"registration_status": "failed",

"message": "Free quota exhausted. Auto-registration failed — please retry later or contact support.",

"request_id": "req_xxx"

}

4. disabled — auto-registration turned off

The platform has globally disabled automatic registration.

JSON
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6

{

"code": "daily_free_quota_exhausted",

"registration_status": "disabled",

"message": "Free quota exhausted. Auto-registration is currently disabled — please use an existing account or API key, or ask your administrator to enable it.",

"request_id": "req_xxx"

}

Anti-bypass protection: While recent_auth_ip:{IP} is alive (TTL window), an IP that has just been authenticated cannot drop the API key and silently revert to anonymous mode. The gateway keeps returning 402 quota-exhausted. This stops users from burning their paid quota and then sneaking back onto the anonymous free tier.

Enum Reference

Allowed values for the enum fields most commonly used in API calls.

Domains (22 values)

generalcodetechfashiontravelhomeecommercegamingfilmmusicfinanceacademiclegalbusinessipsecurityeducationhealthreligiongeoenvironmentenergy

Content Types (9 values)

webnewscodedocacademicdataimagevideoaudio

Zone (2 values)

cnintl

Freshness (4 values)

dayweekmonthyear