Files & Media API

Upload files

Upload images and PDFs to provide context for your searches. Uploaded files are stored in Vercel Blob and can be referenced in search queries.

Endpoint

POST /api/upload

Request

Send a multipart form data request with the file:

file

File

required

The file to upload. Supported types:

Images: JPEG, PNG, GIF
Documents: PDF

Maximum file size: 5MB

Response

url

string

The URL of the uploaded file in Vercel Blob storage

pathname

string

The path to the file

contentType

string

The MIME type of the uploaded file

Example

curl -X POST https://scira.ai/api/upload \
  -F "file=@document.pdf"

Error responses

Status	Description
400	No file uploaded or file validation failed
413	File size exceeds 5MB limit
415	Unsupported file type
500	Upload failed

File validation

Files are validated using this schema:

const FileSchema = z.object({
  file: z
    .instanceof(Blob)
    .refine((file) => file.size <= 5 * 1024 * 1024, {
      message: 'File size should be less than 5MB',
    })
    .refine(
      (file) => {
        const validTypes = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'];
        return validTypes.includes(file.type);
      },
      {
        message: 'File type should be JPEG, PNG, GIF or PDF',
      },
    ),
});

Using uploaded files

After uploading, reference the file URL in your search context:

{
  "query": "Analyze this document",
  "attachments": [
    {
      "url": "https://blob.vercel-storage.com/...",
      "contentType": "application/pdf"
    }
  ]
}

Transcribe audio

Convert audio recordings to text using ElevenLabs’ Scribe transcription model.

Endpoint

POST /api/transcribe

Request

Send a multipart form data request with the audio file:

audio

Blob

required

Audio file to transcribe. Supported formats:

MP3
WAV
M4A
FLAC
OGG

Response

text

string

The transcribed text from the audio

Example

curl -X POST https://scira.ai/api/transcribe \
  -F "audio=@recording.mp3"

Error responses

Status	Description
400	No audio file found in form data
500	Transcription failed

Implementation

The transcription endpoint uses ElevenLabs’ Scribe model:

import { elevenlabs } from '@ai-sdk/elevenlabs';
import { experimental_transcribe as transcribe } from 'ai';

const result = await transcribe({
  model: elevenlabs.transcription('scribe_v1'),
  audio: await audio.arrayBuffer(),
});

Voice mode integration

The transcribe endpoint is primarily used by Scira’s Voice mode feature, which provides:

Real-time voice conversations
Audio input transcription
Voice response synthesis

For voice interactions, see the Voice mode documentation in the Features section.

Export to PDF

Export search results and conversations as PDF documents.

Endpoint

POST /api/export/pdf

Request

chatId

string

required

The ID of the chat/search to export

includeTools

boolean

Whether to include tool call details in the export (default: false)

Response

Returns a PDF file stream with Content-Type: application/pdf.

Example

curl -X POST https://scira.ai/api/export/pdf \
  -H "Content-Type: application/json" \
  -d '{"chatId": "chat_abc123"}' \
  --output search-results.pdf

PDF contents

The exported PDF includes:

Chat title and timestamp
Full conversation history (user queries and AI responses)
Citations and source links
Tool execution details (if includeTools is true)
Formatted code blocks and markdown

Advanced X search (XQL)

XQL (X Query Language) is a Pro feature that provides advanced filtering and search capabilities for X/Twitter content.

Execute advanced X/Twitter searches with precise filtering by date range, X handles, and engagement metrics.

Endpoint

POST /api/xql

Request

query

string

required

Natural language query to search for on X

startDate

string

Start date in YYYY-MM-DD format (defaults to 15 days ago)

endDate

string

End date in YYYY-MM-DD format (defaults to today)

includeXHandles

string[]

Array of X handles to include in search (max 10). Cannot be used with excludeXHandles.

excludeXHandles

string[]

Array of X handles to exclude from search (max 10). Cannot be used with includeXHandles. Note: “grok” is excluded by default.

minLikes

number

Minimum number of likes a post must have

minRetweets

number

Minimum number of retweets a post must have

minReplies

number

Minimum number of replies a post must have

Response

Returns a streaming response with X posts matching the query criteria.

Example

curl -X POST https://scira.ai/api/xql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence breakthroughs",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "includeXHandles": ["OpenAI", "AnthropicAI"],
    "minLikes": 100
  }'

XQL tool schema

The XQL endpoint uses this input schema:

const xqlSchema = z.object({
  query: z.string().describe('Natural language query'),
  startDate: z.string().describe('Start date YYYY-MM-DD'),
  endDate: z.string().describe('End date YYYY-MM-DD'),
  includeXHandles: z.array(z.string()).max(10).optional(),
  excludeXHandles: z.array(z.string()).max(10).optional(),
  minLikes: z.number().optional(),
  minRetweets: z.number().optional(),
  minReplies: z.number().optional(),
});

Use cases

XQL is ideal for:

Market research - Track brand mentions and sentiment
Trend analysis - Monitor emerging topics in specific communities
Competitive intelligence - Follow competitor announcements
Influencer tracking - Monitor posts from key accounts
Event coverage - Search discussions during specific time periods

Search modes

XQL powers Scira’s “X” search mode, which provides:

Real-time post retrieval from X/Twitter
Advanced filtering by engagement metrics
Handle inclusion/exclusion
Date range filtering
Semantic understanding of queries

For more information on search modes, see the Search Modes documentation.

API

Documentation Index

​Upload files

​Endpoint

​Request

​Response

​Example

​Error responses

​File validation

​Using uploaded files

​Transcribe audio

​Endpoint

​Request

​Response

​Example

​Error responses

​Implementation

​Voice mode integration

​Export to PDF

​Endpoint

​Request

​Response

​Example

​PDF contents

​Advanced X search (XQL)

​Endpoint

​Request

​Response

​Example

​XQL tool schema

​Use cases

​Search modes

Build docs developers (and LLMs) love

Upload files

Endpoint

Request

Response

Example

Error responses

File validation

Using uploaded files

Transcribe audio

Endpoint

Request

Response

Example

Error responses

Implementation

Voice mode integration

Export to PDF

Endpoint

Request

Response

Example

PDF contents

Advanced X search (XQL)

Endpoint

Request

Response

Example

XQL tool schema

Use cases

Search modes