Skip to main content

​
Introduction

Scira provides a powerful REST API that enables developers to integrate advanced AI-powered search and research capabilities into their applications. The API supports real-time streaming responses, multiple search modes, and scheduled research agents.

​
Base URL

All API requests should be made to: 
https://scira.ai/api
For local development: 
http://localhost:3000/api

​
Available Endpoints

Scira’s API consists of the following main endpoints:

​
Search Endpoints

  • POST /search - Create a new search and stream AI-generated results
  • GET /search/[id]/stream - Resume or reconnect to an existing search stream

​
Lookout Endpoints

  • POST /lookout - Create and manage scheduled research agents (Pro only)

​
File & Media Endpoints

  • POST /upload - Upload files (images, PDFs) for context-aware search
  • POST /transcribe - Transcribe audio to text using ElevenLabs

​
Export Endpoints

  • POST /export/pdf - Export search results as PDF
  • POST /xql - X Query Language for advanced X/Twitter searches (Pro only)

​
Authentication

Scira uses session-based authentication powered by better-auth. API requests must include valid session cookies obtained through the authentication flow. Some features require different authentication levels:
  • Unauthenticated: Limited to 3 searches per 7 days
  • Authenticated: 100 searches per day for free users
  • Pro subscription: Unlimited searches and access to premium features
See the Authentication page for detailed information.

​
Response Format

Scira’s API uses two response formats depending on the endpoint:

​
JSON Responses

Standard API responses return JSON data: 
{
  "success": true,
  "data": {
    // Response data
  }
}

​
Server-Sent Events (SSE)

Search endpoints stream responses using Server-Sent Events (SSE) for real-time results. The stream includes multiple event types:
  • data - Incremental response chunks
  • tool-call - Tool execution notifications
  • finish - Stream completion with metadata
  • error - Error information

​
Error Handling

The API uses structured error responses with specific error codes:
Error CodeHTTP StatusDescription
unauthorized:auth401Authentication required
unauthorized:model401Model requires authentication
forbidden:chat403Access denied to chat
upgrade_required:model402Pro subscription required
rate_limit:api429Rate limit exceeded
rate_limit:chat429Daily search limit reached
not_found:chat404Chat not found
not_found:stream404Stream not found
bad_request:api400Invalid request
bad_request:database400Database operation failed

​
Error Response Format

{
  "error": {
    "code": "rate_limit:api",
    "message": "You've reached the limit of 3 searches per day for unauthenticated users."
  }
}

​
Rate Limits

Scira implements rate limiting to ensure fair usage:
  • Unauthenticated users: 3 requests per 7 days
  • Free authenticated users: 100 searches per day
  • Pro users: No rate limits
Rate limit information is available in response headers. See Rate Limits for more details.

​
Next Steps

Authentication

Learn how to authenticate your API requests

Search API

Create and stream search results

Lookout API

Set up scheduled research agents

Rate Limits

Understand rate limiting and quotas

Build docs developers (and LLMs) love

Get started for freeTalk to us