Document Storage Service API

Overview

The Document Storage Service is the core service for managing documents, projects, folders, and related functionality in Macro. It provides comprehensive document lifecycle management including creation, editing, versioning, permissions, and deletion. Base URL: /v1 (versioned API) Authentication: All endpoints require JWT authentication via the Authorization header, except internal endpoints which use x-document-storage-service-auth-key.

Core Concepts

Documents

Documents are the primary content type in Macro. Each document has:

Unique document ID (UUID)
Version history with document version IDs
S3-backed storage with CloudFront CDN delivery
Permissions and access control via entity access service
Processing pipeline for text extraction and indexing

Projects

Projects are containers that organize documents and folders hierarchically. They support:

Nested folder structures
Sharing and permissions
Bulk operations

Annotations

Documents support collaborative annotations including:

Anchors (highlighted regions)
Comments on specific document sections
Mentions of users

Documents

Create Document

POST /v1/documents

Creates a new document. The service validates user quotas and permissions before creation.

name

string

required

Document name

project_id

string

Parent project ID (optional)

content

object

Initial document content in Macro’s internal format

string

Unique document ID

version_id

string

Initial version ID for the document

created_at

datetime

Creation timestamp

{
  "name": "Product Roadmap",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": {
    "blocks": [],
    "version": "1.0"
  }
}

Get Document

GET /v1/documents/{document_id}

Retrieves document metadata and content. Returns a signed CloudFront URL for accessing the document.

document_id

string

required

Document ID

string

Document ID

name

string

Document name

url

string

Signed CloudFront URL for document access (expires based on configuration)

version_id

string

Current version ID

owner_id

string

Document owner user ID

Save Document

PUT /v1/documents/{document_id}

Saves changes to a document, creating a new version.

document_id

string

required

Document ID to update

content

object

required

Updated document content

version_id

string

required

Current version ID (for optimistic locking)

The service uses optimistic locking - if the version_id doesn’t match the current version, the save will fail to prevent conflicts.

Edit Document Metadata

PATCH /v1/documents/{document_id}

Updates document metadata (name, project, etc.) without creating a new version.

document_id

string

required

Document ID

name

string

New document name

project_id

string

Move to different project

Copy Document

POST /v1/documents/{document_id}/copy

Creates a copy of the document with all content and formatting.

document_id

string

required

Document ID to copy

name

string

Name for the copied document (defaults to “Copy of [original name]”)

project_id

string

Project ID for the copy

Copying large documents may take several seconds. The user’s quota is checked before copying.

Delete Document

DELETE /v1/documents/{document_id}

Soft-deletes a document (moves to trash). Can be reverted with the revert endpoint.

document_id

string

required

Document ID to delete

Permanently Delete Document

DELETE /v1/documents/{document_id}/permanent

Permanently deletes a document and all its versions from storage.

This operation is irreversible. All document data including versions and S3 objects will be deleted.

Revert Document Deletion

PUT /v1/documents/{document_id}/revert_delete

Restores a soft-deleted document from trash.

Get Document Text

GET /v1/documents/{document_id}/text

Retrieves the extracted plain text content of a document (used for search indexing).

text

string

Extracted plain text content

Export Document

GET /v1/documents/{document_id}/export

Exports the document in various formats (PDF, DOCX, etc.).

format

string

required

Export format: pdf, docx, html

Get Document Permissions

GET /v1/documents/{document_id}/permissions

Retrieves the list of users/teams with access to the document.

permissions

array

Array of permission objects with user/team ID and access level

Get Document Access Token

GET /v1/documents/{document_id}/{version_id}/key

Generates a JWT token for accessing a specific document version via CloudFront.

document_id

string

required

Document ID

version_id

string

required

Document version ID

token

string

JWT access token

expires_at

datetime

Token expiration time

Projects

Create Project

POST /v1/projects

Creates a new project or folder.

name

string

required

Project name

parent_id

string

Parent project ID (for nested folders)

Get Project

GET /v1/projects/{project_id}

Retrieves project metadata and contents (documents and subfolders).

Update Project

PATCH /v1/projects/{project_id}

Updates project metadata.

Delete Project

DELETE /v1/projects/{project_id}

Deletes a project and optionally all contained documents.

delete_contents

boolean

If true, deletes all documents within the project

Annotations

Create Anchor

POST /v1/annotations/anchors

Creates a highlight anchor on a document.

document_id

string

required

Document ID

start_offset

integer

required

Character offset where anchor starts

end_offset

integer

required

Character offset where anchor ends

color

string

Highlight color (hex code)

Create Comment

POST /v1/annotations/comments

Adds a comment to a document or anchor.

document_id

string

required

Document ID

anchor_id

string

Anchor ID (if commenting on a highlight)

content

string

required

Comment text

mentions

array

Array of user IDs to mention

Get Annotations

GET /v1/annotations

Retrieves all annotations for a document.

document_id

string

required

Document ID

Activity & History

Get Recent Activity

GET /v1/activity

Retrieves recent activity across documents.

limit

integer

Number of activity items to return (default: 50)

offset

integer

Pagination offset

Get Document History

GET /v1/history

Retrieves version history for documents.

document_id

string

Filter by specific document

Error Codes

The Document Storage Service uses standard HTTP status codes:

200 - Success
201 - Resource created
400 - Bad request (validation error)
401 - Unauthorized (invalid or missing JWT)
403 - Forbidden (insufficient permissions)
404 - Document not found
409 - Conflict (version mismatch in optimistic locking)
413 - Payload too large (quota exceeded)
500 - Internal server error

Service-Specific Error Codes

error_code

string

Machine-readable error code

message

string

Human-readable error description

Common Error Codes:

QUOTA_EXCEEDED - User has exceeded document quota
VERSION_CONFLICT - Document was modified by another user
DOCUMENT_PROCESSING - Document is still being processed
INVALID_DOCUMENT_ID - Malformed document ID
PERMISSION_DENIED - User lacks required permissions

{
  "error_code": "QUOTA_EXCEEDED",
  "message": "You have reached your document limit of 100 documents. Please upgrade your plan."
}

Data Models

Document

interface Document {
  id: string;              // UUID
  name: string;
  owner_id: string;        // User ID
  project_id?: string;     // Parent project
  version_id: string;      // Current version
  created_at: string;      // ISO 8601 datetime
  updated_at: string;      // ISO 8601 datetime
  deleted_at?: string;     // Soft delete timestamp
  size_bytes: number;      // Document size
  processing_status: "pending" | "completed" | "failed";
}

Project

interface Project {
  id: string;
  name: string;
  owner_id: string;
  parent_id?: string;      // For nested folders
  created_at: string;
  updated_at: string;
  document_count: number;
}

Annotation

interface Anchor {
  id: string;
  document_id: string;
  user_id: string;
  start_offset: number;
  end_offset: number;
  color?: string;
  created_at: string;
}

interface Comment {
  id: string;
  document_id: string;
  anchor_id?: string;
  user_id: string;
  content: string;
  mentions: string[];      // User IDs
  created_at: string;
  updated_at: string;
}

Overview

Core Services

Processing Services

​Overview

​Core Concepts

​Documents

​Projects

​Annotations

​Documents

​Create Document

​Get Document

​Save Document

​Edit Document Metadata

​Copy Document

​Delete Document

​Permanently Delete Document

​Revert Document Deletion

​Get Document Text

​Export Document

​Get Document Permissions

​Get Document Access Token

​Projects

​Create Project

​Get Project

​Update Project

​Delete Project

​Annotations

​Create Anchor

​Create Comment

​Get Annotations

​Activity & History

​Get Recent Activity

​Get Document History

​Error Codes

​Service-Specific Error Codes

​Data Models

​Document

​Project

​Annotation

Build docs developers (and LLMs) love

Overview

Core Concepts

Documents

Projects

Annotations

Documents

Create Document

Get Document

Save Document

Edit Document Metadata

Copy Document

Delete Document

Permanently Delete Document

Revert Document Deletion

Get Document Text

Export Document

Get Document Permissions

Get Document Access Token

Projects

Create Project

Get Project

Update Project

Delete Project

Annotations

Create Anchor

Create Comment

Get Annotations

Activity & History

Get Recent Activity

Get Document History

Error Codes

Service-Specific Error Codes

Data Models

Document

Project

Annotation