Research API Documentation¶

AI-powered research as a service. Get comprehensive, cited research on any topic in seconds.

Base URL¶

https://aegis.rbnk.uk/api/v1/research

Authentication¶

All requests require an API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key_here" https://aegis.rbnk.uk/api/v1/research

Endpoints¶

POST /api/v1/research¶

Execute AI-powered research on any topic.

Request Body:

Field	Type	Required	Description
`topic`	string	Yes	Research topic or question (3-500 chars)
`depth`	string	No	Research depth: `shallow`, `medium`, `deep` (default: `medium`)
`urls`	array	No	Specific URLs to include in research (max 20)
`output_format`	string	No	Output format: `json`, `markdown`, `html` (default: `json`)
`use_cache`	bool	No	Use cached results if available (default: `true`)

Depth Levels:

Depth	Sources	Time	Credits	Best For
`shallow`	3	~15s	1	Quick facts, verification
`medium`	5-7	~30s	3	General research, decisions
`deep`	10+	~2min	10	Comprehensive investigation

Example Request:

curl -X POST https://aegis.rbnk.uk/api/v1/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "topic": "What are best practices for API rate limiting?",
    "depth": "shallow"
  }'

Example Response:

{
  "id": "res_abc123def456",
  "topic": "What are best practices for API rate limiting?",
  "status": "completed",
  "summary": "API rate limiting protects services from abuse...",
  "key_findings": [
    "Token bucket algorithms provide flexible rate limiting",
    "Response headers should communicate limits clearly",
    "Consider tiered limits based on user plans"
  ],
  "detailed_analysis": "Rate limiting is essential for...",
  "sources": [
    {
      "url": "https://example.com/article",
      "title": "API Rate Limiting Guide",
      "snippet": "Rate limiting protects your API...",
      "relevance_score": 0.95
    }
  ],
  "source_count": 3,
  "depth": "shallow",
  "cached": false,
  "duration_ms": 14500,
  "credits_used": 1
}

GET /api/v1/research/credits¶

Check your credit balance and usage.

Example Response:

{
  "credits_remaining": 49,
  "credits_used_today": 1,
  "credits_used_month": 1,
  "tier": "free",
  "rate_limit_remaining": 5,
  "rate_limit_reset_at": "2026-01-06T08:03:17Z"
}

GET /api/v1/research/history¶

Get your research history.

Query Parameters:

Parameter	Type	Default	Description
`limit`	int	20	Results per page (max 100)
`offset`	int	0	Pagination offset

GET /api/v1/research/{id}¶

Retrieve a specific research result by ID.

GET /api/v1/research/pricing¶

Get current pricing tiers and credit costs.

GET /api/v1/research/health¶

Health check endpoint (no auth required).

Pricing Tiers¶

Tier	Credits/Month	Rate Limit	Max Depth	Price
Free	500	10/min	medium	$0
Starter	500	20/min	deep	$9/mo
Pro	5,000	60/min	deep	$49/mo
Enterprise	Unlimited	200/min	deep	Contact

Error Responses¶

Code	Meaning
401	Missing or invalid API key
402	Insufficient credits
403	Feature not available on your tier
429	Rate limit exceeded
500	Research execution failed

Error Response Format:

{
  "detail": {
    "error": "Insufficient credits",
    "error_code": "INSUFFICIENT_CREDITS"
  }
}

Caching¶

Results are cached for 24 hours by default. Identical queries within this window return cached results at no credit cost. Set use_cache: false to force fresh research.

Code Examples¶

Python¶

import requests

response = requests.post(
    "https://aegis.rbnk.uk/api/v1/research",
    headers={"X-API-Key": "your_api_key"},
    json={
        "topic": "What is WebAssembly?",
        "depth": "medium"
    }
)

result = response.json()
print(result["summary"])

JavaScript¶

const response = await fetch("https://aegis.rbnk.uk/api/v1/research", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
  },
  body: JSON.stringify({
    topic: "What is WebAssembly?",
    depth: "medium"
  })
});

const result = await response.json();
console.log(result.summary);

cURL¶

curl -X POST https://aegis.rbnk.uk/api/v1/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"topic": "What is WebAssembly?", "depth": "medium"}'

Getting an API Key¶

Contact us to get an API key for the Research API.

Support¶

Documentation: https://aegis.rbnk.uk/docs
Issues: https://github.com/aegis-agent/aegis-core/issues