Cytherra API Reference

Everything you need to integrate AI-native search into your application. One endpoint, any language, clean results.

Base URL: https://cytherra.comv1.0

Getting Started

Get up and running with Cytherra in three steps:

Create Account

Generate API Key

Create a key in your dashboard

Make a Request

Call the search API with your key

bash
curl -X POST https://cytherra.com/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how does vector search work?"}'

Authentication

All API requests require a Bearer token in the Authorization header. API keys start with cyth_sk_.

Authorization: Bearer cyth_sk_abc123...

Your API key is shown only once when created. Store it securely.

Unauthenticated Access

The search endpoint also works without an API key for testing, but with stricter rate limits (30 requests/minute). Authenticated requests get plan-based limits.

Search Endpoint

POST/api/search

Search the Cytherra index and get an AI-synthesized answer with source citations. Supports hybrid search (BM25 + vector embeddings).

Request Body

Field	Type	Description
`query`REQUIRED	string	The search query. Must be non-empty.
`mode`	"quick" \| "deep"	Search mode. "quick" returns concise answers (default). "deep" returns detailed, multi-source synthesis.
`max_results`	number	Maximum source chunks to retrieve. Default: 5 (quick), 10 (deep).

Response

Field	Type	Description
`answer`REQUIRED	string	AI-synthesized answer based on retrieved sources.
`sources`REQUIRED	Source[]	Array of source objects with title, url, and snippet.
`model`REQUIRED	string	Model used: "cytherra-quick-v1" or "cytherra-deep-v1".
`latency_ms`REQUIRED	number	Total request processing time in milliseconds.
`search_method`REQUIRED	string	Method used: "hybrid", "vector", "bm25", or "fallback".
`cached`REQUIRED	boolean	Whether the result was served from cache.

Source Object

Field	Type	Description
`title`REQUIRED	string	Title of the source page.
`url`REQUIRED	string	URL of the original source.
`snippet`REQUIRED	string	Relevant text excerpt from the source.

Example Response

json
{
  "answer": "Vector search works by converting text into high-dimensional embeddings...",
  "sources": [
    {
      "title": "Understanding Vector Search",
      "url": "https://example.com/vector-search",
      "snippet": "Vector search uses mathematical representations..."
    }
  ],
  "model": "cytherra-quick-v1",
  "latency_ms": 342,
  "search_method": "hybrid",
  "cached": false
}

Search (GET)

GET/api/search?q=your+query

A simplified GET endpoint for quick searches. Uses “quick” mode with 5 results. Useful for browser testing and simple integrations.

bash
curl "https://cytherra.com/api/search?q=what+is+RAG"

Calling GET without a q parameter returns API info and available endpoints.

Extract Endpoint

POST/api/extract

Extract clean, readable content from any URL. Returns Markdown with boilerplate removed. Requires authentication.

Request Body

Field	Type	Description
`url`REQUIRED	string	The URL to extract content from.

Response

Field	Type	Description
`url`REQUIRED	string	The URL that was extracted.
`title`REQUIRED	string	Page title.
`content`REQUIRED	string	Clean Markdown content with boilerplate removed.
`word_count`REQUIRED	number	Word count of extracted content.

bash
curl -X POST https://cytherra.com/api/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Vector_database"}'

Research Endpoint

POST/api/research

Perform multi-step research on a topic. Cytherra will search, extract, and synthesize information from multiple sources into a coherent report. Requires authentication (Enterprise plan or above).

Request Body

Field	Type	Description
`objective`REQUIRED	string	The research objective or question.
`depth`	"quick" \| "standard" \| "deep"	Research depth. Quick (2 steps), standard (5 steps, default), deep (10 steps).

bash
curl -X POST https://cytherra.com/api/research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective": "Compare RAG architectures for production use", "depth": "deep"}'

Rate Limits

Rate limits are enforced per IP for unauthenticated requests and per API key for authenticated requests.

Plan	Searches/month	Rate Limit
Free	1,000	10 req/min
Pro ($49/mo)	10,000	60 req/min
Enterprise ($199/mo)	100,000	300 req/min

When you exceed your rate limit, the API returns 429 Too Many Requests.

Error Codes

Code	Meaning	Description
`200`	OK	Request succeeded.
`400`	Bad Request	Missing or invalid parameters (e.g., empty query, invalid JSON).
`401`	Unauthorized	Invalid or disabled API key.
`429`	Rate Limited	Too many requests. Back off and retry.
`500`	Server Error	Internal error. Contact support if persistent.

Error Response Format

json
{
  "error": "query field is required"
}

Code Examples

bash
curl -X POST https://cytherra.com/api/search \
  -H "Authorization: Bearer cyth_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best practices for RAG pipelines",
    "mode": "deep",
    "max_results": 5
  }'

MCP Integration

Cytherra integrates with any MCP-compatible AI assistant (Claude Desktop, Cursor, Windsurf, and more) via the @cytherra/mcp-server package.

Cursor / Claude Desktop / Windsurf

Add to your MCP config file:

json
{
  "mcpServers": {
    "cytherra": {
      "command": "npx",
      "args": ["-y", "@cytherra/mcp-server"],
      "env": {
        "CYTHERRA_API_URL": "https://cytherra.com",
        "CYTHERRA_API_KEY": "cyth_sk_your_key_here"
      }
    }
  }
}

Available MCP Tools

cytherra_search

Search the indexed knowledge base

Params: query, max_tokens?, max_results?

cytherra_extract

Extract clean content from a URL

Params: url

cytherra_research

Multi-step research synthesis

Params: objective, depth? ("quick"|"standard"|"deep")

Need help integrating?

Visit your Connect page for platform-specific setup instructions with your API key pre-filled. Or email support@cytherra.com.