Skip to main content

​
Overview

The Search API enables you to create AI-powered searches and receive streaming responses in real-time. It supports multiple AI models, search modes, and tool integrations for comprehensive research capabilities.

​
Endpoints

​
POST /api/search

Create a new search and stream AI-generated results.

​
Request Body

​
id
string
required
Unique identifier for the chat/conversation. Use UUIDv7 for optimal performance.
​
messages
array
required
Array of message objects representing the conversation history.
​
model
string
required
AI model to use for generation. Examples:
  • "scira-default" - Default balanced model
  • "scira-gpt5" - OpenAI GPT-5 (Pro only)
  • "scira-anthropic" - Claude 3.5 Sonnet
  • "scira-google" - Gemini 2.0 Flash
  • "scira-grok-4-fast-think" - xAI Grok-4 with thinking
​
group
string
required
Search mode/group determining tool availability:
  • "research" - Standard research mode
  • "extreme" - Deep research mode (Pro only, limited usage)
  • "code" - Code-focused mode
  • "general" - General conversation mode
​
selectedVisibilityType
string
Chat visibility: "private" or "public". Defaults to "private".
​
timezone
string
User’s timezone (e.g., "America/New_York") for time-aware responses.
​
isCustomInstructionsEnabled
boolean
Whether to include user’s custom instructions. Defaults to true.
​
searchProvider
string
Search provider preference: "tavily" or "exa". Defaults to "tavily".
​
extremeSearchProvider
string
Extreme search provider: "exa" or "tavily". Defaults to "exa".
​
selectedConnectors
array
Array of connector IDs to enable for this search.

​
Example Request

curl -X POST https://scira.ai/api/search \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=<your-session-token>" \
  -d '{
    "id": "01933d5e-8f2a-7890-b1c2-d3e4f5a6b7c8",
    "messages": [
      {
        "id": "msg-01933d5e-8f2a-7890-b1c2-d3e4f5a6b7c9",
        "role": "user",
        "content": "What are the latest developments in quantum computing?",
        "parts": [
          {
            "type": "text",
            "text": "What are the latest developments in quantum computing?"
          }
        ],
        "experimental_attachments": []
      }
    ],
    "model": "scira-default",
    "group": "research",
    "selectedVisibilityType": "private",
    "timezone": "America/New_York",
    "searchProvider": "tavily"
  }'

​
Response Format

The endpoint returns a Server-Sent Events (SSE) stream with multiple event types: Stream Event Types:
​
data-appendText
object
Incremental text chunks for the AI response
{
  "type": "data-appendText",
  "data": "Quantum computing has seen significant advances..."
}
​
data-toolCall
object
Tool execution notification
{
  "type": "data-toolCall",
  "data": {
    "toolName": "web_search",
    "args": {"queries": ["quantum computing 2025"]}
  }
}
​
data-toolResult
object
Tool execution results
{
  "type": "data-toolResult",
  "data": {
    "result": "[Search results...]"
  }
}
​
data-finish
object
Stream completion with metadata
{
  "type": "data-finish",
  "data": {
    "model": "scira-default",
    "completionTime": 4.52,
    "totalTokens": 2847,
    "inputTokens": 1234,
    "outputTokens": 1613
  }
}
​
data-chat_title
object
Auto-generated chat title (for new chats)
{
  "type": "data-chat_title",
  "data": {
    "title": "Quantum Computing Developments"
  },
  "transient": true
}

​
JavaScript Example

const response = await fetch('https://scira.ai/api/search', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id: crypto.randomUUID(),
    messages: [
      {
        id: crypto.randomUUID(),
        role: 'user',
        content: 'Explain machine learning',
        parts: [{ type: 'text', text: 'Explain machine learning' }],
        experimental_attachments: []
      }
    ],
    model: 'scira-default',
    group: 'research',
    selectedVisibilityType: 'private'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log('Event:', data.type);
      console.log('Data:', data.data);
    }
  }
}

​
Python Example

import requests
import json
import uuid

url = "https://scira.ai/api/search"
headers = {
    "Content-Type": "application/json",
    "Cookie": "better-auth.session_token=<your-session-token>"
}

payload = {
    "id": str(uuid.uuid4()),
    "messages": [
        {
            "id": str(uuid.uuid4()),
            "role": "user",
            "content": "What is artificial intelligence?",
            "parts": [{"type": "text", "text": "What is artificial intelligence?"}],
            "experimental_attachments": []
        }
    ],
    "model": "scira-default",
    "group": "research",
    "selectedVisibilityType": "private"
}

response = requests.post(url, headers=headers, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data = json.loads(line_str[6:])
            print(f"Event: {data['type']}")
            print(f"Data: {data['data']}")

​
GET /api/search/[id]/stream

Resume or reconnect to an existing search stream. This endpoint enables resumable streams, allowing clients to reconnect if the connection is interrupted.

​
Path Parameters

​
id
string
required
The chat ID to resume streaming for

​
Authentication

Requires valid session cookie. Returns 401 if not authenticated.

​
Authorization

Users can only resume streams for:
  • Their own private chats
  • Public chats (any user)

​
Example Request

curl -X GET https://scira.ai/api/search/01933d5e-8f2a-7890-b1c2-d3e4f5a6b7c8/stream \
  -H "Cookie: better-auth.session_token=<your-session-token>"

​
Response

Returns an SSE stream with the same event types as POST /api/search. Behavior:
  1. Active Stream: If the stream is still active, resumes from the current position
  2. Recently Completed: If the stream completed within 15 seconds, returns the final message
  3. Older Completion: Returns empty stream (204 No Content)

​
JavaScript Example

const chatId = '01933d5e-8f2a-7890-b1c2-d3e4f5a6b7c8';
const response = await fetch(`https://scira.ai/api/search/${chatId}/stream`, {
  credentials: 'include'
});

if (response.status === 204) {
  console.log('Stream not available');
} else {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    // Process SSE events...
  }
}

​
Available Tools

Depending on the group parameter, different tools are available:

​
Research Mode Tools

  • web_search - Web search via Tavily or Exa
  • academic_search - Search academic papers and publications
  • youtube_search - Search YouTube videos
  • reddit_search - Search Reddit discussions
  • x_search - Search X/Twitter posts
  • retrieve - Retrieve and parse web page content
  • extreme_search - Deep multi-step research (limited)

​
General Tools (All Modes)

  • weather - Get weather data
  • datetime - Get current date/time
  • text_translate - Translate text
  • currency_converter - Convert currencies
  • stock_chart - Get stock data
  • coin_data - Get cryptocurrency data
  • find_place_on_map - Find locations
  • nearby_places_search - Search nearby places
  • track_flight - Track flight status
  • movie_or_tv_search - Search movies/TV shows

​
Pro User Tools

  • code_interpreter - Execute Python code
  • search_memories - Search user’s saved memories
  • add_memory - Save information to memory
  • connectors_search - Search connected data sources

​
Rate Limits

Unauthenticated:
  • 3 searches per 7 days
Authenticated (Free):
  • 100 searches per day
  • Limited extreme search usage
Pro Users:
  • Unlimited searches
  • Unlimited extreme search

​
Error Responses

​
unauthorized:auth
401
Authentication required
{
  "error": {
    "code": "unauthorized:auth",
    "message": "Authentication required to use Extreme Search mode"
  }
}
​
unauthorized:model
401
Model requires authentication
{
  "error": {
    "code": "unauthorized:model",
    "message": "scira-gpt5 requires authentication"
  }
}
​
upgrade_required:model
402
Pro subscription required
{
  "error": {
    "code": "upgrade_required:model",
    "message": "scira-gpt5 requires a Pro subscription"
  }
}
​
rate_limit:api
429
Rate limit exceeded
{
  "error": {
    "code": "rate_limit:api",
    "message": "You've reached the limit of 3 searches per day for unauthenticated users."
  }
}
​
rate_limit:chat
429
Daily search limit reached
{
  "error": {
    "code": "rate_limit:chat",
    "message": "Daily search limit reached"
  }
}
​
forbidden:chat
403
Chat access denied
{
  "error": {
    "code": "forbidden:chat",
    "message": "This chat belongs to another user"
  }
}
​
not_found:stream
404
Stream not found
{
  "error": {
    "code": "not_found:stream",
    "message": "Stream not found"
  }
}

​
Best Practices

Use UUIDv7 (time-ordered UUIDs) for chat and message IDs for better database performance and sortability.
Implement reconnection logic using the GET /api/search/[id]/stream endpoint to resume interrupted streams.
Process SSE events as they arrive rather than buffering the entire response for better user experience.
The API automatically prunes messages when history exceeds 10 messages. Consider managing context client-side for better control.
Select models based on your needs:
  • scira-default for balanced performance
  • scira-gpt5 for highest quality (Pro)
  • scira-google for fast responses
  • scira-grok-4-fast-think for reasoning tasks

Build docs developers (and LLMs) love

Get started for freeTalk to us