# Orbita

Search API for AI agents over a curated, expanding index. Hosted pilot endpoint: POST https://orbita.surf/v1/search. Use Authorization: Bearer orb_live_... with an account API key. Signup grants $1 of test credit once per account.

Results contain excerpt, published_at (nullable/absent) and evidence_ids; query is a string. Content/date/domain/language/highlight controls from earlier drafts are NOT supported. No live URL crawling or full-web guarantee.

- [API reference](https://orbita.surf/landing/docs.html): actual requests, responses, errors and billing.
- [Complete machine-readable contract](https://orbita.surf/landing/llms-full.txt)
- [OpenAPI](https://orbita.surf/landing/openapi.json)
- [Prices](https://orbita.surf/v1/pricing)
- [Create an account](https://orbita.surf/landing/signup.html)
- [Legal & Trust](https://orbita.surf/landing/legal.html): private_preview_draft; hosted pilot, effective production terms not finalized.
- [Historical Search100 report](https://orbita.surf/landing/search100-report.html): frozen-corpus benchmark, not current hosted performance or whole-web coverage.
- [System outcomes](https://orbita.surf/landing/final-report.html): historical measurements and constraints.

Implementation details are private. Model providers including OpenRouter may process request data; see Privacy and Subprocessors. Query text is not stored in account usage history.

## Request parameters

- query (string, required): 1–1,000 characters after trimming. Searches the indexed corpus; a URL is not crawled by this endpoint.
- mode (auto (default), fast, standard, pro, deep, ultra): Auto selects one fixed mode. The response reports requested_mode, resolved_mode and selection_reason.
- limit (integer 1–100): Default: the mode maximum. Capped to that maximum and max_results. Fewer returned rows do not change the price.
- max_mode (fast…ultra, default ultra): Depth ceiling for Auto. Explicit mode requests retain their selected mode.
- max_cost_usd (positive number, optional): Maximum retail charge for one request in USD. Auto selects a mode that fits; an explicit mode over the ceiling is rejected before billing.
- max_results (integer 1–100, default 100): Caps returned result count, not candidate depth or the selected mode.
- timeout_ms (integer 500–30000, default 30000): Server deadline. Failed requests are refunded. A client-side timeout alone does not prove that server work failed.
- links (none, relevant, all; default relevant): Links extracted from retrieved sources. Only available links are returned.
- context.enabled (boolean, default false): Enables the higher-priced Compact product. Source excerpts are already included without Compact.
- context.strategy (evidence (default) or summary): Evidence assembles original source blocks. Summary is automated and validated; it falls back to Evidence if generation fails. There is no human review per request.
- context.max_tokens (500, 1000, 2000 or 4000; default 1000): Context output token ceiling. Complete blocks may be withheld if they do not fit. This differs from the mode input allowance.
- context.citations / dates (boolean, default true): Include source-scoped citation IDs and known dates inside Context. Unknown dates are not invented.

## Example

POST https://orbita.surf/v1/search
Authorization: Bearer YOUR_ACCOUNT_API_KEY
Content-Type: application/json

{
  "query": "How do Cloudflare Workers and Durable Objects work together?",
  "mode": "fast",
  "limit": 5,
  "timeout_ms": 30000,
  "links": "relevant",
  "context": {
    "enabled": false
  }
}

## Response

query is a string. results[] expose id, url, title, source, published_at, last_checked, version_hash, score, excerpt and evidence_ids. Optional ranking fields are not confidence estimates. No full page text or character-offset highlights are promised.

requested_mode, resolved_mode and selection_reason explain depth selection. status may be empty_index, no_results or retrieval_candidates. context is always an object: enabled=false/status=disabled means no Compact; ready, fallback and empty distinguish enabled outcomes. Generated summaries receive automatic source validation, not human review. Links are extracted from indexed source content.

usage.cost_usd is the retail charge, not provider COGS. took_ms is server duration; ms is a compatibility alias. HTTP 200 does not establish that a candidate answers the query.

## Billing and limits

All rates are USD per 1,000 successful searches:
Fast 2.99 / Compact 4.99 (up to 5 results)
Standard 4.99 / Compact 6.99 (up to 10)
Pro 7.99 / Compact 11.99 (up to 25)
Deep 9.99 / Compact 14.99 (up to 50)
Ultra 13.99 / Compact 19.99 (up to 100)

Mode Context input allowances: 3000/5000/10000/20000/50000 tokens. Separate Context output ceilings: 500/1000/2000/4000. Smaller result lists do not discount the selected mode. Successful empty results and cache hits are billed. Compact fallback retains the Compact price. Failed searches are refunded. A single Fast call changes $1 to $0.99701. No paid subscription, top-ups or invoice delivery is implemented.

60 searches/minute/account, 2 concurrent/account, 8 concurrent/server process. All account keys share the limit. Limits are process-local. Body limit 32 KiB. No X-RateLimit or Retry-After headers are promised.

## Errors and retries

Error body: {"error":"message", "message":"message"}; message may be omitted on some handlers. Optional field identifies an account form field. There is no error.type or request_id contract.
HTTP 400 invalid input; 401 invalid credentials; 402 insufficient credit; 403 CSRF/origin/host; 404 missing route; 409 conflict/reused Idempotency-Key; 413 body too large; 415 JSON required; 422 invalid signup/legal fields; 429 capacity; 500 runtime/upstream; 504 deadline.

Send a unique Idempotency-Key per NEW search. The same key cannot charge twice and returns 409 rather than replaying a response. If transport failed, do not automatically retry with a new key: the server may have completed the original. Check account usage. A confirmed failed request is refunded; retry after backoff with a new key.

## Accounts

POST /v1/auth/signup requires handle, email, password, accept_terms=true, accept_privacy=true and current terms_version/privacy_version from /landing/legal.json. POST /v1/auth/signin accepts ident and password. Sessions use HttpOnly/Secure/SameSite=Strict cookies; mutating dashboard requests require X-CSRF-Token. GET /v1/me returns user and CSRF token. GET/POST /v1/keys; PATCH/DELETE /v1/keys/:id. GET /v1/usage?days=30 and /v1/events?limit=40 return account-scoped data. POST /v1/me/password changes the password and revokes sessions. POST /v1/auth/signout invalidates the session. DELETE /v1/me removes the account. Corpus admin routes are unavailable in the public service.

Events are limited to 90 days in the API and purged during new event writes. Email verification and email recovery are unavailable; legal status remains private_preview_draft.

## MCP

The repository contains a stdio reference server; no published npm package or hosted MCP HTTP/SSE endpoint is provided. Run from repository root:
ORBITA_API_URL=https://orbita.surf ORBITA_API_KEY=orb_live_... node prototype/src/mcp-server.mjs
The only search tool is orbita_search. Configure an absolute script path in your MCP client. Use an account API key, never a corpus-admin credential.