Skip to content

Files

File Management Endpoints

Upload File

Uploads a file. This is Step 1 of a two-step workflow. Use the MCP tool upload_document (Step 2) to link the file to a memory.

Endpoint: POST /api/files/upload

Query Parameters: - Authentication: MCP token (Bearer) or OAuth2

Body (multipart/form-data): - file (required): File to upload - memory_id (optional): Memory ID to link the file to (can be linked later via MCP tool) - description (optional): File description - tags[] (optional): Array of tags - category (optional): File category

Response:

{
  "success": true,
  "file": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "memory_id": null,
    "filename": "documentation.pdf",
    "mime_type": "application/pdf",
    "size": 1024000,
    "description": "Project documentation",
    "tags": ["docs", "architecture"],
    "category": "documentation",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "File uploaded successfully. Use upload_document MCP tool with file_id to link to a memory."
}

Example (Step 1 - Upload):

curl -X POST "https://akashic-mcp.com/api/files/upload" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -F "[email protected]" \
  -F "description=Project architecture documentation" \
  -F "tags[]=architecture" \
  -F "category=documentation"

Step 2 - Link to Memory (MCP Tool):

After uploading, use the upload_document MCP tool with the file_id from the response to link the file to a memory. See MCP Tools - Document Management for details.

Get File

Downloads a file by ID.

Endpoint: GET /api/files/:id

Query Parameters: - Authentication: MCP token (Bearer) or OAuth2 (or authenticate)

Response: File binary data with appropriate Content-Type header

Example:

curl -H "Authorization: Bearer mcp_YOUR_TOKEN" "https://akashic-mcp.com/api/files/file-uuid" \
  --output documentation.pdf

List Files

Lists files with optional filters.

Endpoint: GET /api/files

Query Parameters: - Authentication: MCP token (Bearer) or OAuth2 (or authenticate) - memory_id (optional): Filter by memory ID - category (optional): Filter by category - tags (optional): Filter by tags (comma-separated)

Response:

{
  "files": [
    {
      "id": "file-uuid",
      "memory_id": "mem-123",
      "filename": "documentation.pdf",
      "mime_type": "application/pdf",
      "size": 1024000,
      "description": "Project documentation",
      "tags": ["docs", "architecture"],
      "category": "documentation",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1
}

Example:

curl -H "Authorization: Bearer mcp_YOUR_TOKEN" "https://akashic-mcp.com/api/files?memory_id=mem-123"

Update File Metadata

Updates file metadata without changing the file.

Endpoint: PUT /api/files/:id/metadata

Query Parameters: - Authentication: MCP token (Bearer) or OAuth2 (or authenticate)

Body: - description (optional): New description - tags (optional): New tags array - category (optional): New category

Example:

curl -X PUT "https://akashic-mcp.com/api/files/file-uuid/metadata" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "tags": ["updated", "tags"],
    "category": "documentation"
  }'

Delete File

Deletes a file by ID.

Endpoint: DELETE /api/files/:id

Query Parameters: - Authentication: MCP token (Bearer) or OAuth2 (or authenticate)

Response:

{
  "success": true,
  "message": "File deleted successfully"
}

Example:

curl -X DELETE -H "Authorization: Bearer mcp_YOUR_TOKEN" "https://akashic-mcp.com/api/files/file-uuid"