Semantic retrieval over indexed chunks via POST /retrievals with top_k, metadata filters, reranking, and recency bias, plus agentic /responses generation that grounds answers in retrieved context.
openapi: 3.0.1
info:
title: Ragie API
description: >-
Ragie is a fully-managed Retrieval-Augmented Generation (RAG) as-a-service
platform. This specification covers the documented REST surface for
ingesting documents, retrieving chunks, generating grounded responses,
managing data connectors, extracting entities, and isolating data with
partitions. All requests are authenticated with a Bearer API key.
termsOfService: https://www.ragie.ai/terms-of-service
contact:
name: Ragie Support
url: https://www.ragie.ai
email: support@ragie.ai
version: '1.0'
servers:
- url: https://api.ragie.ai
security:
- bearerAuth: []
tags:
- name: Documents
- name: Retrievals
- name: Connections
- name: Entities
- name: Partitions
paths:
/documents:
post:
operationId: createDocument
tags:
- Documents
summary: Create Document
description: >-
Ingest a document by uploading a file. The document is processed
asynchronously through Ragie's pipeline (partitioning, chunking,
indexing) until it reaches the ready state.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The binary file to ingest.
mode:
type: string
enum: [fast, hi_res]
description: Partition strategy controlling extraction fidelity.
metadata:
type: object
additionalProperties: true
description: Custom key-value metadata for filtering.
name:
type: string
external_id:
type: string
partition:
type: string
responses:
'200':
description: Document created.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimited'
get:
operationId: listDocuments
tags:
- Documents
summary: List Documents
parameters:
- name: cursor
in: query
schema:
type: string
- name: page_size
in: query
schema:
type: integer
default: 25
- name: partition
in: query
schema:
type: string
- name: filter
in: query
schema:
type: string
description: JSON metadata filter.
responses:
'200':
description: A page of documents.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentList'
'401':
$ref: '#/components/responses/Unauthorized'
/documents/raw:
post:
operationId: createDocumentRaw
tags:
- Documents
summary: Create Document Raw
description: Ingest a document from raw inline text rather than a file.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: string
description: Raw text content to ingest.
metadata:
type: object
additionalProperties: true
name:
type: string
external_id:
type: string
partition:
type: string
responses:
'200':
description: Document created.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/documents/from-url:
post:
operationId: createDocumentFromUrl
tags:
- Documents
summary: Create Document From URL
description: Ingest a document by fetching it from a remote URL.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
format: uri
mode:
type: string
enum: [fast, hi_res]
metadata:
type: object
additionalProperties: true
name:
type: string
external_id:
type: string
partition:
type: string
responses:
'200':
description: Document created.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/documents/{document_id}:
get:
operationId: getDocument
tags:
- Documents
summary: Get Document
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: The document.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateDocumentFile
tags:
- Documents
summary: Update Document File
description: Replace a document's contents with a new uploaded file.
parameters:
- $ref: '#/components/parameters/DocumentId'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
responses:
'200':
description: Document updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteDocument
tags:
- Documents
summary: Delete Document
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Document deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/documents/{document_id}/metadata:
patch:
operationId: patchDocumentMetadata
tags:
- Documents
summary: Patch Document Metadata
parameters:
- $ref: '#/components/parameters/DocumentId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- metadata
properties:
metadata:
type: object
additionalProperties: true
responses:
'200':
description: Metadata updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'401':
$ref: '#/components/responses/Unauthorized'
/documents/{document_id}/content:
get:
operationId: getDocumentContent
tags:
- Documents
summary: Get Document Content
description: Returns the processed text content of the document.
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Document content.
content:
application/json:
schema:
type: object
properties:
content:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/documents/{document_id}/summary:
get:
operationId: getDocumentSummary
tags:
- Documents
summary: Get Document Summary
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Document summary.
content:
application/json:
schema:
type: object
properties:
summary:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/documents/{document_id}/source:
get:
operationId: getDocumentSource
tags:
- Documents
summary: Get Document Source
description: Returns the original source file for the document.
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: The source file.
content:
application/octet-stream:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
/documents/{document_id}/chunks:
get:
operationId: getDocumentChunks
tags:
- Documents
summary: Get Document Chunks
parameters:
- $ref: '#/components/parameters/DocumentId'
- name: cursor
in: query
schema:
type: string
- name: page_size
in: query
schema:
type: integer
responses:
'200':
description: A page of chunks.
content:
application/json:
schema:
type: object
properties:
chunks:
type: array
items:
$ref: '#/components/schemas/Chunk'
cursor:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/documents/{document_id}/chunks/{chunk_id}:
get:
operationId: getDocumentChunk
tags:
- Documents
summary: Get Document Chunk
parameters:
- $ref: '#/components/parameters/DocumentId'
- name: chunk_id
in: path
required: true
schema:
type: string
responses:
'200':
description: The chunk.
content:
application/json:
schema:
$ref: '#/components/schemas/Chunk'
'401':
$ref: '#/components/responses/Unauthorized'
/retrievals:
post:
operationId: retrieve
tags:
- Retrievals
summary: Retrieve
description: >-
Run a semantic retrieval over indexed chunks and return the most
relevant scored chunks for the query.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievalRequest'
responses:
'200':
description: Scored chunks.
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievalResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimited'
/responses:
post:
operationId: createResponse
tags:
- Retrievals
summary: Create Response
description: >-
Generate an agentic response grounded in content retrieved from the
knowledge base.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- input
properties:
input:
type: string
description: The user input or question.
partition:
type: string
instructions:
type: string
filter:
type: object
additionalProperties: true
responses:
'200':
description: The generated response.
content:
application/json:
schema:
type: object
properties:
id:
type: string
output:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/connections:
post:
operationId: createConnection
tags:
- Connections
summary: Create Connection
description: Create a managed data connector to an external source.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionCreate'
responses:
'200':
description: Connection created.
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
get:
operationId: listConnections
tags:
- Connections
summary: List Connections
parameters:
- name: cursor
in: query
schema:
type: string
- name: page_size
in: query
schema:
type: integer
responses:
'200':
description: A page of connections.
content:
application/json:
schema:
type: object
properties:
connections:
type: array
items:
$ref: '#/components/schemas/Connection'
cursor:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/connections/oauth:
post:
operationId: createOAuthRedirectUrl
tags:
- Connections
summary: Create OAuth Redirect URL
description: Create an OAuth redirect URL to begin a connection authorization flow.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- source_type
properties:
source_type:
type: string
description: The connector source type, e.g. google_drive, notion.
redirect_uri:
type: string
format: uri
partition:
type: string
responses:
'200':
description: OAuth redirect URL.
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
'401':
$ref: '#/components/responses/Unauthorized'
/connections/source_type:
get:
operationId: listConnectionSourceTypes
tags:
- Connections
summary: List Connection Source Types
responses:
'200':
description: Supported connector source types.
content:
application/json:
schema:
type: object
properties:
source_types:
type: array
items:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/connections/{connection_id}:
get:
operationId: getConnection
tags:
- Connections
summary: Get Connection
parameters:
- $ref: '#/components/parameters/ConnectionId'
responses:
'200':
description: The connection.
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateConnection
tags:
- Connections
summary: Update Connection
parameters:
- $ref: '#/components/parameters/ConnectionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
additionalProperties: true
mode:
type: string
responses:
'200':
description: Connection updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteConnection
tags:
- Connections
summary: Delete Connection
parameters:
- $ref: '#/components/parameters/ConnectionId'
responses:
'200':
description: Connection deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/connections/{connection_id}/stats:
get:
operationId: getConnectionStats
tags:
- Connections
summary: Get Connection Stats
parameters:
- $ref: '#/components/parameters/ConnectionId'
responses:
'200':
description: Connection statistics.
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
/connections/{connection_id}/sync:
post:
operationId: syncConnection
tags:
- Connections
summary: Sync Connection
description: Trigger an on-demand sync of the connection.
parameters:
- $ref: '#/components/parameters/ConnectionId'
responses:
'200':
description: Sync triggered.
'401':
$ref: '#/components/responses/Unauthorized'
/connections/{connection_id}/enabled:
put:
operationId: setConnectionEnabled
tags:
- Connections
summary: Set Connection Enabled
parameters:
- $ref: '#/components/parameters/ConnectionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
responses:
'200':
description: Connection enabled state updated.
'401':
$ref: '#/components/responses/Unauthorized'
/connections/{connection_id}/limit:
put:
operationId: setConnectionLimits
tags:
- Connections
summary: Set Connection Limits
parameters:
- $ref: '#/components/parameters/ConnectionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
pages_processed_limit_monthly:
type: integer
responses:
'200':
description: Connection limits updated.
'401':
$ref: '#/components/responses/Unauthorized'
/instructions:
post:
operationId: createInstruction
tags:
- Entities
summary: Create Instruction
description: >-
Create an extraction instruction that defines a JSON schema of entities
Ragie should extract from matching documents.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InstructionCreate'
responses:
'200':
description: Instruction created.
content:
application/json:
schema:
$ref: '#/components/schemas/Instruction'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
get:
operationId: listInstructions
tags:
- Entities
summary: List Instructions
responses:
'200':
description: A page of instructions.
content:
application/json:
schema:
type: object
properties:
instructions:
type: array
items:
$ref: '#/components/schemas/Instruction'
'401':
$ref: '#/components/responses/Unauthorized'
/instructions/{instruction_id}:
put:
operationId: updateInstruction
tags:
- Entities
summary: Update Instruction
parameters:
- $ref: '#/components/parameters/InstructionId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InstructionCreate'
responses:
'200':
description: Instruction updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Instruction'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteInstruction
tags:
- Entities
summary: Delete Instruction
parameters:
- $ref: '#/components/parameters/InstructionId'
responses:
'200':
description: Instruction deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/instructions/{instruction_id}/entities:
get:
operationId: getInstructionExtractedEntities
tags:
- Entities
summary: Get Instruction Extracted Entities
parameters:
- $ref: '#/components/parameters/InstructionId'
responses:
'200':
description: Extracted entities for the instruction.
content:
application/json:
schema:
type: object
properties:
entities:
type: array
items:
$ref: '#/components/schemas/Entity'
'401':
$ref: '#/components/responses/Unauthorized'
/documents/{document_id}/entities:
get:
operationId: getDocumentExtractedEntities
tags:
- Entities
summary: Get Document Extracted Entities
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Extracted entities for the document.
content:
application/json:
schema:
type: object
properties:
entities:
type: array
items:
$ref: '#/components/schemas/Entity'
'401':
$ref: '#/components/responses/Unauthorized'
/partitions:
post:
operationId: createPartition
tags:
- Partitions
summary: Create Partition
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PartitionCreate'
responses:
'200':
description: Partition created.
content:
application/json:
schema:
$ref: '#/components/schemas/Partition'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
get:
operationId: listPartitions
tags:
- Partitions
summary: List Partitions
parameters:
- name: cursor
in: query
schema:
type: string
- name: page_size
in: query
schema:
type: integer
responses:
'200':
description: A page of partitions.
content:
application/json:
schema:
type: object
properties:
partitions:
type: array
items:
$ref: '#/components/schemas/Partition'
cursor:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/partitions/{partition_id}:
get:
operationId: getPartition
tags:
- Partitions
summary: Get Partition
parameters:
- $ref: '#/components/parameters/PartitionId'
responses:
'200':
description: The partition.
content:
application/json:
schema:
$ref: '#/components/schemas/Partition'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updatePartition
tags:
- Partitions
summary: Update Partition
parameters:
- $ref: '#/components/parameters/PartitionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Partition updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Partition'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deletePartition
tags:
- Partitions
summary: Delete Partition
parameters:
- $ref: '#/components/parameters/PartitionId'
responses:
'200':
description: Partition deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/partitions/{partition_id}/limits:
put:
operationId: setPartitionLimits
tags:
- Partitions
summary: Set Partition Limits
parameters:
- $ref: '#/components/parameters/PartitionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
pages_processed_limit_monthly:
type: integer
pages_hosted_limit_monthly:
type: integer
responses:
'200':
description: Partition limits updated.
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Ragie API key passed as a Bearer token in the Authorization header.
parameters:
DocumentId:
name: document_id
in: path
required: true
schema:
type: string
format: uuid
ConnectionId:
name: connection_id
in: path
required: true
schema:
type: string
format: uuid
InstructionId:
name: instruction_id
in: path
required: true
schema:
type: string
format: uuid
PartitionId:
name: partition_id
in: path
required: true
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PaymentRequired:
description: Plan limit reached or payment required.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: Request validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Document:
type: object
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- pending
- partitioning
- partitioned
- refined
- chunked
- indexed
- summary_indexed
- ready
- failed
name:
type: string
external_id:
type: string
partition:
type: string
metadata:
type: object
additionalProperties: true
chunk_count:
type: integer
page_count:
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
DocumentList:
type: object
properties:
documents:
type: array
items:
$ref: '#/components/schemas/Document'
cursor:
type: string
Chunk:
type: object
properties:
id:
type: string
format: uuid
document_id:
type: string
format: uuid
text:
type: string
index:
type: integer
metadata:
type: object
additionalProperties: true
RetrievalRequest:
type: object
required:
- query
properties:
query:
type: string
description: The query to search with when retrieving document chunks.
top_k:
type: integer
default: 8
description: Maximum number of chunks to return.
filter:
type: object
additionalProperties: true
description: >-
Metadata filter supporting operators $eq, $ne, $gt, $gte, $lt,
$lte, $in, $nin.
rerank:
type: boolean
default: false
max_chunks_per_document:
type: integer
recency_bias:
type: boolean
default: false
partition:
type: string
RetrievalResponse:
type: object
properties:
scored_chunks:
type: array
items:
$ref: '#/components/schemas/ScoredChunk'
ScoredChunk:
type: object
properties:
id:
type: string
format: uuid
text:
type: string
score:
type: number
format: float
document_id:
type: string
format: uuid
document_name:
type: string
document_metadata:
type: object
additionalProperties: true
ConnectionCreate:
type: object
required:
- source_type
properties:
source_type:
type: string
name:
type: string
partition:
type: string
metadata:
type: object
additionalProperties: true
Connection:
type: object
properties:
id:
type: string
format: uuid
source_type:
type: string
name:
type: string
enabled:
type: boolean
partition:
type: string
created_at:
type
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ragie-ai/refs/heads/main/openapi/ragie-ai-openapi.yml