Menu
Use Mirra to document upload, processing, and management with multi-graph sharing. Covers all Documents SDK operations via REST API.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use Mirra to living dashboards — natively-rendered grids of typed widgets (stat, image_card, list, progress, sparkline) that flows keep current by pushing data into them..... Covers all Dashboards SDK operations via REST API.
Use Mirra to execute user-defined scripts in aws lambda. Covers all Scripts SDK operations via REST API.
Use Mirra to the places a space publishes to — its corporate x, blog, newsletter — and the drafted copy waiting to go out to them. use listchannels to see what this space.... Covers all Space Channels SDK operations via REST API.
Use Mirra to the space's shared work-ledger. items are agreed work with status (open/proposed/done), an owner, artifact links, and progress notes; every teammate's home f.... Covers all Work Items SDK operations via REST API.
The team work-ledger ritual for agents on a Mirra space: track agreed work, propose discoveries (then ask in chat), relay approvals, close what ships, and publish ONE narrated update card per work burst — revise, never stack. Rides the Mirra items adapter / MCP work-ledger tools.
START HERE for anything Mirra. Load this whenever the repo you're working in has a .mirra/ directory (it's linked to a Mirra team space), or your human mentions their Mirra space, teammates' updates, or the team ledger. Directs the ambient team rituals — record work in the shared ledger, publish update cards, ask the space before expanding scope — and indexes every detail-level mirra-* skill.
| name | mirra-document |
| description | Use Mirra to document upload, processing, and management with multi-graph sharing. Covers all Documents SDK operations via REST API. |
| allowed-tools | Read, Bash(curl:*, jq:*) |
Document upload, processing, and management with multi-graph sharing
You need the user's API key. Ask for these if not provided:
API_KEY: Mirra API key (generated in Mirra app > Settings > API Keys)API_URL: Defaults to https://api.fxn.world (only ask if they mention a custom server)All operations use a single POST endpoint with the resource ID and method in the body:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{
"resourceId": "document",
"method": "{operation}",
"params": { ...args }
}' | jq .
Replace {operation} with the operation name from the table below.
Legacy alternative:
POST ${API_URL}/api/sdk/v1/document/{operation}with args as the request body also works but is not recommended for new integrations.
| Operation | Description |
|---|---|
upload | Upload and process a document (PDF, DOCX, TXT, MD). Returns normalized flat structure. |
get | Get a single document by its documentId, including the full document text. The complete text is i... |
getStatus | Get document processing status. Returns normalized flat structure. |
getChunks | Get all chunks for a document, in order. Returns normalized flat chunk structures. For the docume... |
delete | Delete a document and all its chunks. Returns normalized flat structure. |
share | Share a document to another graph (group or user-contact). Returns normalized flat structure. |
unshare | Remove document access from a graph. Returns normalized flat structure. |
listGraphs | List all graphs a document is shared in. Returns normalized flat graph structures. |
search | Semantic (meaning-based) search across document chunks in a graph. Takes a natural-language `quer... |
list | List documents in a graph (metadata only — does not include document text). Returns normalized fl... |
uploadUpload and process a document (PDF, DOCX, TXT, MD). Returns normalized flat structure.
Arguments:
file (string, required): Base64 encoded file contentfilename (string, required): Original filename with extensionmimeType (string, required): MIME type (application/pdf, text/plain, etc.)graphId (string, optional): Target graph ID (defaults to user's personal graph)title (string, optional): Custom document titleproductTags (array, optional): Array of product tags for categorizationReturns:
AdapterOperationResult: Returns FLAT structure with: documentId, chunkCount, graphIds[], primaryGraphId, processingTimeMs. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"upload","params":{"file":"<value>","filename":"<value>","mimeType":"<value>"}}' | jq .
getGet a single document by its documentId, including the full document text. The complete text is in the extractedText field — read or summarize a document directly from it (no need to fetch or stitch chunks). Also returns metadata (title, filename, mimeType, fileSize, processingStatus, etc.) and the document's chunks[]. To find content across many documents by meaning, use search; to enumerate documents in a graph, use list.
Arguments:
documentId (string, required): Document ID to retrieve (e.g. "document:..."). The parameter is named documentId, not id.Returns:
AdapterOperationResult: Returns FLAT structure with: documentId, title, filename, mimeType, fileSize, processingStatus, chunkCount, graphIds[], primaryGraphId, createdAt, createdByUserId, hasMultipleGraphs, extractedText (full document text — use this to read the document), chunks[]. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"get","params":{"documentId":"<ID>"}}' | jq .
getStatusGet document processing status. Returns normalized flat structure.
Arguments:
documentId (string, required): Document ID to checkReturns:
AdapterOperationResult: Returns FLAT structure with: documentId, processingStatus, processingError, chunkCount, extractedAt, processingCompletedAt. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"getStatus","params":{"documentId":"<ID>"}}' | jq .
getChunksGet all chunks for a document, in order. Returns normalized flat chunk structures. For the document's full text in one field, prefer get (it returns extractedText); use getChunks only when you need the per-chunk breakdown or chunk positions.
Arguments:
documentId (string, required): Document IDReturns:
AdapterOperationResult: Returns { documentId, count, chunks[] }. Each chunk has FLAT fields: chunkId, documentId, content, position. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"getChunks","params":{"documentId":"<ID>"}}' | jq .
deleteDelete a document and all its chunks. Returns normalized flat structure.
Arguments:
documentId (string, required): Document ID to deleteReturns:
AdapterOperationResult: Returns FLAT structure with: documentId, deleted, chunksDeleted. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"delete","params":{"documentId":"<ID>"}}' | jq .
shareShare a document to another graph (group or user-contact). Returns normalized flat structure.
Arguments:
documentId (string, required): Document ID to sharetargetGraphId (string, required): Target graph ID to share toshareReason (string, optional): Optional reason for sharingReturns:
AdapterOperationResult: Returns FLAT structure with: documentId, graphIds[], sharedToGraphId, sharedByUserId, sharedAt. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"share","params":{"documentId":"<ID>","targetGraphId":"<ID>"}}' | jq .
unshareRemove document access from a graph. Returns normalized flat structure.
Arguments:
documentId (string, required): Document IDgraphId (string, required): Graph ID to remove access fromReturns:
AdapterOperationResult: Returns FLAT structure with: documentId, graphIds[], removedGraphId. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"unshare","params":{"documentId":"<ID>","graphId":"<ID>"}}' | jq .
listGraphsList all graphs a document is shared in. Returns normalized flat graph structures.
Arguments:
documentId (string, required): Document IDReturns:
AdapterOperationResult: Returns { documentId, count, graphs[] }. Each graph has FLAT fields: graphId, isPrimary, sharedAt, sharedByUserId, shareReason. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"listGraphs","params":{"documentId":"<ID>"}}' | jq .
searchSemantic (meaning-based) search across document chunks in a graph. Takes a natural-language query (not a documentId) and returns the best-matching passages in results[], each with content, score, documentId, and position. Use this to find relevant content across documents; to read one specific document in full, use get instead.
Arguments:
query (string, required): Natural-language search query (what you are looking for). This is NOT a documentId.graphId (string, optional): Graph ID to search in (defaults to user's graph)limit (number, optional): Maximum results (default: 10)threshold (number, optional): Similarity threshold 0-1 (default: 0.7)Returns:
AdapterOperationResult: Returns { graphId, count, results[] }. Each result has FLAT fields: chunkId, documentId, content, score, position. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"search","params":{"query":"search term"}}' | jq .
listList documents in a graph (metadata only — does not include document text). Returns normalized flat document structures. To read a document's content, call get with its documentId; to search content by meaning, use search.
Arguments:
graphId (string, optional): Graph ID to list documents from (defaults to user's graph)limit (number, optional): Maximum results (default: 50)offset (number, optional): Pagination offset (default: 0)Returns:
AdapterOperationResult: Returns { graphId, count, documents[] }. Each document has FLAT fields: documentId, title, filename, mimeType, fileSize, processingStatus, chunkCount, graphIds[], createdAt, createdByUserId. No nested objects.
Example:
curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
-H "Content-Type: application/json" \
-H "x-api-key: ${API_KEY}" \
-d '{"resourceId":"document","method":"list","params":{}}' | jq .
All SDK responses return the operation payload wrapped in a standard envelope:
{
"success": true,
"data": { ... }
}
The data field contains the operation result. Error responses include:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message"
}
}
jq . to pretty-print responses, jq .data to extract just the payloaddata.results or directly in data (check examples)--fail-with-body to curl to see error details on HTTP failuresexport API_KEY="your-key"