Skip to main content
Documentation

Documents

The Documents service provides file storage for foundation and reference documents — the briefs, PRDs, brand guidelines, spreadsheets, architecture diagrams, and other files that a project starts with. Documents are stored on cloud object storage and accessed via download URLs. All responses return metadata only — file content is never returned inline.

Base URL: https://api.minolith.io/v1/documents

Authentication: All endpoints require an API key via the Authorization header:

Authorization: Bearer mlth_your_api_key_here

Pricing: No credits are consumed for API or MCP operations (uploads, reads, updates, deletes). File storage counts against your project's disk usage quota, which is billed at 5 credits per MB per month.

Requirements: Documents requires a Team ($15/month) or Teams Plus ($25/month) subscription. Solo plan accounts receive a 403 team_plan_required error. Trial accounts have full access during the trial period.

Limits

Limit Value
Documents per project 500
Max file size 50 MB
Max tags per document 20
Max title length 500 characters
Max description length 5,000 characters

Accepted File Types

Category Formats
Documents PDF, DOCX, DOC, RTF, ODT, Pages, TXT, MD, CSV, JSON, XML
Spreadsheets XLSX, XLS, ODS, Numbers
Presentations PPTX, PPT, ODP, Keynote
Images PNG, JPG, JPEG, GIF, SVG, WebP, ICO, TIFF
Archives ZIP

Executables, scripts, video, audio, PSD, and AI files are not accepted.

Endpoints

POST /v1/documents/

Upload a new document with metadata.

Content-Type: multipart/form-data

Form Fields:

Field Type Required Description
file file yes The file to upload (max 50 MB)
title string yes Document title (max 500 chars)
description string no What this document is and why it matters (max 5,000 chars)
priority string no high, normal, or low. Default: normal
scope string no Lowercase alphanumeric with hyphens (e.g. brand, api, design)
tags string no JSON array of tag strings (max 20 tags, each lowercase alphanumeric with hyphens)

Response (201 Created):

{
  "id": "doc_a1b2c3d4e5f6",
  "title": "Project Brief",
  "description": "The original project brief from the client.",
  "priority": "high",
  "scope": "brand",
  "filename": "project-brief.pdf",
  "mime_type": "application/pdf",
  "file_size": 245760,
  "tags": ["brief", "foundation"],
  "download_url": "https://api.minolith.io/v1/documents/doc_a1b2c3d4e5f6/download?expires=1743700800&sig=abc123...",
  "created_at": "2026-04-02 12:00:00",
  "updated_at": "2026-04-02 12:00:00"
}

GET /v1/documents/

List documents with optional filtering and cursor-based pagination.

Query Parameters:

Parameter Type Description
tags string Comma-separated tags. Returns documents matching ANY tag.
scope string Filter by scope.
priority string Filter by priority: high, normal, low.
search string Search title and description.
limit integer Max results per page (default 20, max 100).
cursor string Cursor from previous response for pagination.

Response (200 OK):

{
  "data": [
    {
      "id": "doc_a1b2c3d4e5f6",
      "title": "Project Brief",
      "description": "The original project brief.",
      "priority": "high",
      "scope": "brand",
      "filename": "project-brief.pdf",
      "mime_type": "application/pdf",
      "file_size": 245760,
      "tags": ["brief", "foundation"],
      "download_url": "https://api.minolith.io/v1/documents/doc_a1b2c3d4e5f6/download?expires=1743700800&sig=abc123...",
      "created_at": "2026-04-02 12:00:00",
      "updated_at": "2026-04-02 12:00:00"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "limit": 20
  }
}

GET /v1/documents/{id}

Get a single document's metadata and download URL.

Response (200 OK):

{
  "id": "doc_a1b2c3d4e5f6",
  "title": "Project Brief",
  "description": "The original project brief.",
  "priority": "high",
  "scope": "brand",
  "filename": "project-brief.pdf",
  "mime_type": "application/pdf",
  "file_size": 245760,
  "tags": ["brief", "foundation"],
  "download_url": "https://api.minolith.io/v1/documents/doc_a1b2c3d4e5f6/download?expires=1743700800&sig=abc123...",
  "created_at": "2026-04-02 12:00:00",
  "updated_at": "2026-04-02 12:00:00"
}

GET /v1/documents/{id}/download

Download the actual file. Returns the raw file bytes with the appropriate Content-Type and Content-Disposition headers.

Accepts either a signed URL (returned by all API and MCP responses) or a Bearer token. Signed download URLs expire after 1 hour. If a URL has expired, fetch the document metadata again to get a fresh signed URL.

The file is streamed from cloud storage through the API — there is no public download URL.

Response: Binary file content with headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="project-brief.pdf"
Content-Length: 245760

PUT /v1/documents/{id}

Update a document's metadata. Cannot replace the file itself — delete and re-upload to change the file.

Content-Type: application/json

Body Fields (all optional):

Field Type Description
title string Updated title (max 500 chars)
description string Updated description (max 5,000 chars). Set to null to clear.
priority string high, normal, or low
scope string Updated scope. Set to null to clear.
tags array Replace all tags. Pass [] to clear.

Response (200 OK): Returns the updated document (same format as GET).

DELETE /v1/documents/{id}

Permanently delete a document and its file from storage. This cannot be undone.

Response: 204 No Content

MCP Tools

The Documents service is available via MCP for direct integration with AI coding tools.

Connection

claude mcp add --transport http minolith https://mcp.minolith.io \
  --header "Authorization: Bearer mlth_your_api_key_here" \
  --header "X-Minolith-Agent: your-agent-name"

upload_document

Upload a foundation document with metadata. File content is provided as base64-encoded data.

Parameters:

Parameter Type Required Description
title string yes Document title (max 500 chars)
file_data string yes Base64-encoded file content
filename string yes Original filename with extension (e.g. brief.pdf)
description string no Description (max 5,000 chars)
priority string no high, normal, or low. Default: normal
scope string no Scope (lowercase alphanumeric with hyphens)
tags array no Tags (max 20, lowercase alphanumeric with hyphens)

list_documents

List documents with optional filtering.

Parameters:

Parameter Type Required Description
tags array no Filter by tags (matches ANY)
scope string no Filter by scope
priority string no Filter by priority
search string no Search title and description
limit integer no Max results (default 20, max 100)
cursor string no Pagination cursor

get_document

Get a document's metadata and download URL by ID.

Parameters:

Parameter Type Required Description
id string yes Document ID (doc_xxxxxxxx)

update_document

Update a document's metadata. Cannot replace the file.

Parameters:

Parameter Type Required Description
id string yes Document ID (doc_xxxxxxxx)
title string no Updated title
description string no Updated description
priority string no Updated priority
scope string no Updated scope
tags array no Replace tags

delete_document

Permanently delete a document and its file from storage.

Parameters:

Parameter Type Required Description
id string yes Document ID (doc_xxxxxxxx)

Bootstrap Integration

When you call bootstrap, the response includes a documents summary if any documents exist:

{
  "documents": {
    "total": 5,
    "high_priority": [
      {
        "id": "doc_a1b2c3d4e5f6",
        "title": "Project Brief",
        "filename": "project-brief.pdf",
        "mime_type": "application/pdf"
      }
    ]
  }
}

This tells the agent that foundation documents are available without listing everything. Query list_documents or get_document when you need the full details or download URL.

Last updated: 6 Apr 2026