Documentation

Get Started with Ragily

Everything you need to integrate web search, content extraction, site crawling, research reports, document ingestion, and unified query into your application.

Quick Start

Make your first API call in under a minute. Grab your API key from the dashboard and run:

# Search the web

curl -X POST https://api.ragily.com/v1/search \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "latest AI research papers", "max_results": 5}'

Base URL

https://api.ragily.com/v1

Authentication

Authenticated endpoints require a Bearer token in the Authorization header. API keys are scoped to your account and can be managed from your dashboard.

Authorization: Bearer rgl_your_api_key_here

Credits

Each API call consumes credits based on the operation:

Endpoint	Credits
`POST /v1/search` (basic)	1 credit
`POST /v1/search` (advanced depth)	2 credits
`POST /v1/search` + include_answer	+1 credit
`POST /v1/extract`	1 credit per 5 URLs
`POST /v1/crawl`	1 credit per 5 pages
`POST /v1/research` (basic)	5 credits
`POST /v1/research` (deep)	15 credits
`POST /v1/documents`	1 credit
`POST /v1/documents/search`	1 credit
`POST /v1/query`	2–3 credits (varies by sources + answer)

GET

/v1/health

Public health check endpoint. No authentication required. Returns server status, version, uptime, and timestamp.

Response

statusstring

Server status: "ok", "degraded", or "error".

versionstring

API version string.

uptimenumber

Server uptime in seconds.

timestampstring

Current server time in ISO 8601 format.

# Example

curl https://api.ragily.com/v1/health

POST

/v1/search

Search the web and return structured results with snippets, URLs, and relevance scores. Optionally include an AI-generated answer.

Request Body

querystringrequired

Search query. 1–2000 characters.

search_depthstringdefault: "basic"

"basic" or "advanced". Advanced uses more credits but returns deeper results.

topicstringdefault: "general"

"general", "news", or "finance".

max_resultsintegerdefault: 5

Maximum number of results. 1–20.

time_rangestring

Filter by recency: "day", "week", "month", or "year".

include_domainsstring[]

Only include results from these domains.

exclude_domainsstring[]

Exclude results from these domains.

countrystring

ISO 3166-1 alpha-2 country code for localized results.

include_answerbooleandefault: false

Include an AI-generated answer synthesized from results. Costs +1 credit.

include_raw_contentbooleandefault: false

Include full raw page content for each result.

include_imagesbooleandefault: false

Include image results.

Response

querystring

The original search query.

answerstring | null

AI-generated answer, if requested.

resultsobject[]

Array of results. Each contains title, url, content (snippet), score (relevance), and optionally raw_content and published_date.

imagesstring[]

Array of image URLs, if requested.

response_timenumber

Request duration in milliseconds.

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

POST

/v1/extract

Extract clean, readable content from one or more URLs. Returns markdown or plain text via Mozilla Readability.

Request Body

urlsstring[]required

Array of URLs to extract content from. 1–20 URLs.

extract_depthstringdefault: "basic"

"basic" or "detailed". Detailed extraction includes more metadata.

formatstringdefault: "markdown"

Output format: "markdown" or "text".

timeoutintegerdefault: 15000

Per-URL fetch timeout in milliseconds. 1000–30000.

Response

resultsobject[]

Successfully extracted content. Each contains url and raw_content.

failed_resultsobject[]

URLs that failed to extract. Each contains url and error message.

response_timenumber

Request duration in milliseconds.

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

POST

/v1/crawl

Start an async crawl job. The crawler recursively follows links from the given URL, deduplicates pages via a Redis seen-set, and enforces an atomic page budget. Poll the status endpoint to retrieve results.

Request Body

urlstringrequired

The starting URL to crawl.

max_depthintegerdefault: 1

Maximum link depth to follow. 1–3.

max_pagesintegerdefault: 10

Maximum number of pages to crawl. 1–100.

Response

job_idstring

Unique identifier for the crawl job. Use this to poll status.

statusstring

Job status: "queued".

urlstring

The starting URL.

max_depthinteger

Configured max depth.

max_pagesinteger

Configured max pages.

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

# Example

curl -X POST https://api.ragily.com/v1/crawl \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com", "max_depth": 2, "max_pages": 20}'

GET

/v1/crawl/:id

Retrieve the status and results of a crawl job by its ID.

Response

job_idstring

The crawl job identifier.

urlstring

The starting URL.

statusstring

"queued", "crawling", "completed", or "failed".

max_depthinteger

Configured max depth.

max_pagesinteger

Configured max pages.

total_pagesinteger

Number of pages successfully crawled so far.

total_failedinteger

Number of pages that failed to crawl.

created_atstring

Job creation timestamp (ISO 8601).

completed_atstring | null

Job completion timestamp, or null if still running.

pagesobject[]

Array of crawled pages. Each contains url, status, title, raw_content, depth, and crawled_at.

request_idstring

Unique request identifier for support.

# Example

curl https://api.ragily.com/v1/crawl/job_abc123 \ -H "Authorization: Bearer YOUR_API_KEY"

POST

/v1/research

Start an async research job. The system searches, extracts, and synthesizes a structured report from multiple sources. Returns immediately with a job ID for polling.

Request Body

querystringrequired

Research query. 1–2000 characters.

research_depthstringdefault: "basic"

"basic" (1 round, 5 credits) or "deep" (3 rounds, 15 credits).

Response (202)

job_idstring

Unique identifier for the research job.

statusstring

Job status: "queued".

querystring

The original research query.

research_depthstring

The configured depth.

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

# Example

curl -X POST https://api.ragily.com/v1/research \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "impact of AI on healthcare", "research_depth": "deep"}'

GET

/v1/research/:id

Retrieve the status and results of a research job. No additional credits charged.

Response

job_idstring

The research job identifier.

querystring

The original research query.

research_depthstring

The configured depth.

statusstring

"queued", "researching", "completed", or "failed".

current_roundinteger

Current research round (1-indexed).

total_roundsinteger

Total number of research rounds.

reportobject | null

The synthesized research report, or null if not yet complete.

created_atstring

Job creation timestamp (ISO 8601).

completed_atstring | null

Job completion timestamp, or null if still running.

request_idstring

Unique request identifier for support.

POST

/v1/documents

Ingest a document for semantic search. Supports two modes: send a URL via JSON, or upload a file via multipart/form-data (max 10MB). Accepted formats: .txt, .md, .pdf, .docx. The document is automatically chunked, embedded, and indexed.

Request Body (JSON)

urlstringrequired

URL of the document to fetch and ingest.

filenamestring

Override filename (used to determine file type if URL path is ambiguous).

Request Body (multipart/form-data)

fileFilerequired

The file to upload. Max 10MB. Accepted: .txt, .md, .pdf, .docx.

Response (202)

document_idstring

Unique identifier for the document.

statusstring

Processing status: "queued".

filenamestring

The document filename.

mime_typestring

Detected MIME type.

file_sizeinteger

File size in bytes (0 for URL-based until processed).

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

GET

/v1/documents/:id

Get document metadata and processing status.

Response

document_idstring

The document identifier.

filenamestring

The document filename.

mime_typestring

MIME type.

file_sizeinteger

File size in bytes.

statusstring

"queued", "processing", "completed", or "failed".

total_chunksinteger

Number of indexed chunks.

metadataobject | null

Extracted document metadata.

created_atstring

Document creation timestamp (ISO 8601).

completed_atstring | null

Processing completion timestamp, or null if still running.

request_idstring

Unique request identifier for support.

GET

/v1/documents

List all documents for the authenticated API key.

Query Parameters

limitintegerdefault: 20

Number of documents to return. 1–100.

offsetintegerdefault: 0

Number of documents to skip.

Response

documentsobject[]

Array of documents with document_id, filename, mime_type, file_size, status, total_chunks, created_at, completed_at.

totalinteger

Total number of documents.

request_idstring

Unique request identifier for support.

DELETE

/v1/documents/:id

Delete a document and all its indexed chunks.

Response

document_idstring

The deleted document identifier.

deletedboolean

Always true.

request_idstring

Unique request identifier for support.

POST

/v1/documents/search

Semantic search across your ingested documents using vector similarity. Returns the most relevant document chunks.

Request Body

querystringrequired

Search query. 1–2000 characters.

max_resultsintegerdefault: 5

Maximum number of chunks to return. 1–20.

document_idsstring[]

Limit search to specific document IDs (UUIDs).

Response

querystring

The original search query.

resultsobject[]

Array of results. Each contains chunk_id, document_id, filename, content, chunk_index, and similarity (0–1).

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

POST

/v1/query

Unified query across web search and your documents. Returns merged results from both sources with an optional AI-generated answer synthesized from all content.

Request Body

querystringrequired

Search query. 1–2000 characters.

include_webbooleandefault: true

Include web search results.

include_documentsbooleandefault: true

Include document search results.

max_resultsintegerdefault: 5

Maximum results per source. 1–20.

search_depthstringdefault: "basic"

"basic" or "advanced". Controls web search depth.

include_answerbooleandefault: true

Generate an AI answer from combined web and document sources.

document_idsstring[]

Limit document search to specific document IDs (UUIDs).

Response

querystring

The original query.

web_resultsobject[]

Web search results. Each contains title, url, content, and score.

document_resultsobject[]

Document search results. Each contains chunk_id, document_id, filename, content, chunk_index, and similarity.

answerstring | null

AI-generated answer synthesized from all sources, or null if not requested or no results found.

response_timenumber

Request duration in milliseconds.

usageobject

Contains credits_used, credits_remaining, and optionally overage_credits.

request_idstring

Unique request identifier for support.

# Example

curl -X POST https://api.ragily.com/v1/query \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "quantum computing breakthroughs", "include_web": true, "include_documents": true, "include_answer": true}'

Prefer an SDK?

We offer official client libraries for TypeScript, Python, and more.

View SDKs