Document Endpoints
Complete API reference for document operations
This page documents all available operations for uploading, managing, and searching documents on the Mirra platform.
Upload and process a new document. The document is extracted, chunked, embedded, and stored in the specified graph.
POST /api/sdk/v1/documents/upload
{
file: "base64EncodedFileContent...",
filename: "quarterly-report.pdf",
mimeType: "application/pdf",
title: "Q4 2024 Financial Report",
author: "Finance Team",
productTags: ["finance", "quarterly", "2024"],
graphId: "user:abc-123" // Optional, defaults to personal graph
}
{
"success": true,
"data": {
"documentId": "doc_abc123def456",
"chunkCount": 47,
"processingTimeMs": 2340,
"graphIds": ["user:abc-123"]
}
}
Retrieve full document metadata including all chunks.
GET /api/sdk/v1/documents/{documentId}
{
"success": true,
"data": {
"document": {
"documentId": "doc_abc123",
"filename": "report.pdf",
"title": "Q4 2024 Report",
"author": "Finance Team",
"uploadedAt": 1699876543000,
"chunkCount": 47
},
"chunks": [
{
"chunkId": "chunk_123",
"content": "The primary revenue drivers...",
"position": 0,
"pageNumber": 12
}
]
}
}
Check the processing status of a document without retrieving all chunks.
GET /api/sdk/v1/documents/{documentId}/status
{
"success": true,
"data": {
"documentId": "doc_abc123",
"status": "completed",
"chunkCount": 47,
"uploadedAt": 1699876543000
}
}
Retrieve all chunks for a document without the parent metadata.
GET /api/sdk/v1/documents/{documentId}/chunks
{
"success": true,
"data": {
"chunks": [
{
"chunkId": "chunk_123",
"documentId": "doc_abc123",
"content": "Chunk text content...",
"position": 0,
"pageNumber": 1,
"charOffset": 0
}
],
"count": 47
}
}
Delete a document and all its associated chunks from the knowledge graph.
DELETE /api/sdk/v1/documents/{documentId}
{
"success": true,
"data": {
"chunksDeleted": 47
}
}
Note: Deleting a document removes it from all graphs it's shared in. This operation cannot be undone.
Share a document to another graph (group or user contact).
POST /api/sdk/v1/documents/{documentId}/share
{
"targetGraphId": "group:team-finance",
"shareReason": "For quarterly review meeting"
}
{
"success": true,
"data": {
"documentId": "doc_abc123",
"graphIds": ["user:abc-123", "group:team-finance"],
"shareEvent": {
"sharedAt": 1699876543000,
"sharedBy": "user:abc-123",
"reason": "For quarterly review meeting"
}
}
}
Remove document access from a specific graph.
DELETE /api/sdk/v1/documents/{documentId}/share/{graphId}
{
"success": true,
"data": {
"documentId": "doc_abc123",
"graphIds": ["user:abc-123"]
}
}
Note: You cannot unshare a document from its primary graph (the graph it was originally uploaded to).
List all graphs a document is shared in, with metadata about each share event.
GET /api/sdk/v1/documents/{documentId}/graphs
{
"success": true,
"data": {
"documentId": "doc_abc123",
"graphs": [
{
"graphId": "user:abc-123",
"graphType": "personal",
"graphName": "Personal Graph",
"isPrimary": true,
"sharedAt": 1699876543000,
"sharedByUserId": "user:abc-123"
},
{
"graphId": "group:team-finance",
"graphType": "group",
"graphName": "Finance Team",
"isPrimary": false,
"sharedAt": 1699877000000,
"sharedByUserId": "user:abc-123",
"shareReason": "For quarterly review meeting"
}
]
}
}
Perform semantic search across document chunks within a specific graph.
POST /api/sdk/v1/documents/search
{
"query": "quarterly revenue growth analysis",
"graphId": "user:abc-123", // Optional, defaults to personal graph
"limit": 10, // Optional, default: 10
"threshold": 0.7 // Optional, default: 0.7
}
{
"success": true,
"data": {
"results": [
{
"chunkId": "chunk_123",
"documentId": "doc_abc123",
"documentName": "q4-2024.pdf",
"content": "The primary revenue drivers for Q4...",
"score": 0.892,
"position": 23,
"pageNumber": 12
}
],
"count": 5
}
}
The threshold parameter filters results below a minimum similarity score. Lower thresholds return more results but may include less relevant chunks.
List all documents accessible in a specific graph with pagination support.
GET /api/sdk/v1/documents
graphId (string, optional) - Graph to list documents from (defaults to personal graph)limit (number, optional) - Results per page (default: 10)offset (number, optional) - Pagination offset (default: 0)
{
"success": true,
"data": {
"documents": [
{
"documentId": "doc_abc123",
"filename": "report.pdf",
"title": "Q4 2024 Report",
"author": "Finance Team",
"chunkCount": 47,
"uploadedAt": 1699876543000,
"productTags": ["finance", "quarterly"]
}
],
"count": 15
}
}
- Overview - Document concepts and processing pipeline
- Examples - Practical code examples
- Technical Notes - Supported formats, embeddings, and troubleshooting
