Comprehensive Guide to Macro Inc API Endpoints and Interfaces

Macro Inc exposes a distributed set of HTTP and WebSocket interfaces built on Axum, with each microservice mounting its own router under service-specific ports and unified Swagger documentation at /docs.

The macro-inc/macro repository implements a Rust-based microservices architecture where individual services expose RESTful and streaming endpoints. Each service defines its routing logic in src/api/mod.rs using the Axum web framework, shares authentication via MacroAuthorizationExtractor, and publishes OpenAPI specifications via utoipa.

Connection Gateway API

The Connection Gateway handles real-time WebSocket connections and message routing between entities. Its router construction in [services/connection_gateway/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/connection_gateway/src/api/mod.rs#L19-L25) mounts distinct sub-routers for connection management and messaging.

WebSocket Connections

The primary entry point for real-time communication upgrades HTTP requests to WebSocket connections.

• GET / – Initiates a WebSocket handshake via ws_handler defined in the connection module.

Message Routing Endpoints

Scoped under /message, these endpoints manage entity-to-entity communication:

• POST /message/send/{entity_type}/{entity_id} – Sends a targeted message to a specific entity.
• POST /message/batch_send – Dispatches messages to multiple recipients in a single request.
• POST /message/batch_send_unique – Batch sends with deduplication logic.

Additional tracking endpoints are mounted under /track via the entities router for analytics and presence monitoring.

Static File Service API

The Static File Service bifurcates its API surface into public and internal routes. Its main router in [services/static_file_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/static_file_service/src/api/mod.rs#L75-L80) nests services under /api for external clients and /internal for service-to-service communication.

Public File Operations (/api)

• PUT /api/file/presigned_url – Generates a presigned URL for direct client uploads.
• GET /api/file/metadata – Retrieves file metadata by identifier.
• GET /api/file/{id} – Downloads a stored file object.
• DELETE /api/file/{id} – Removes a specific file from storage.
• POST /api/file/bulk_delete – Deletes multiple files atomically.

Internal Service Endpoints (/internal)

Internal routes facilitate inter-service file management without exposing operations to external clients, secured via internal authentication headers.

Document Storage and Cognition APIs

Document handling splits between persistence (Document Storage Service) and AI-driven processing (Document Cognition Service).

Document Storage Endpoints

Defined in [services/document_storage_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/document_storage_service/src/api/mod.rs#L99-L115), this service manages the document lifecycle:

• POST /documents – Creates a new document record.
• GET /documents/{id} – Retrieves document details.
• PATCH /documents/{id} – Updates document metadata or content.
• DELETE /documents/{id} – Permanently deletes a document.
• GET /threads/{id} – Fetches conversation threads associated with a document.
• GET /health – Returns service health status.

Document Cognition and Streaming

The Document Cognition Service in [services/document_cognition_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/document_cognition_service/src/api/mod.rs#L83-L131) provides AI-powered interactions:

• POST /stream/chat – Establishes a streaming chat session for document queries.
• POST /preview – Generates document previews and thumbnails.
• GET /id_mapping/{id} – Resolves external IDs to internal document references.
• POST /id_mapping – Creates new ID mappings for external integrations.

Supporting Microservices

Convert Service

Located in [services/convert_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/convert_service/src/api/mod.rs#L46-L48):

• POST /convert – Transforms documents between formats (e.g., DOCX to PDF).
• POST /backfill/docx – Processes legacy DOCX files for migration.
• GET /health – Service availability check.

Email and Notification Services

Email Service ([services/email_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/email_service/src/api/mod.rs#L67)):

• POST /webhook – Receives Gmail webhook events for synchronization.
• GET /health – Health status endpoint.

Notification Service ([services/notification_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/notification_service/src/api/mod.rs#L70-L79)):

• POST /user_notification – Dispatches notifications to specific users.
• DELETE /unsubscribe/{token} – Handles user unsubscription requests.

Image Proxy and Unfurl Services

• Image Proxy ([services/image_proxy_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/image_proxy_service/src/api/mod.rs#L48)): GET /proxy – Fetches and caches remote images securely.
• Unfurl Service ([services/unfurl_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/unfurl_service/src/api/mod.rs#L55)): GET /unfurl/{url} – Generates rich link previews with metadata extraction.

Authentication and Security Patterns

All Macro Inc API endpoints enforce authentication through MacroAuthorizationExtractor, which validates JWT tokens or session cookies before routing requests to handlers. The Authentication Service ([services/authentication_service/src/api/mod.rs](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/api/mod.rs#L79)) manages:

• OAuth2 provider integrations (Google, Microsoft).
• Session token generation and validation.
• Mobile welcome email workflows.
• Account merging logic for duplicate user resolution.

Practical API Usage Examples

Interact with the Macro Inc microservices using standard HTTP clients. Each service typically listens on a port defined in its environment configuration (e.g., 8090 for Connection Gateway, 8091 for Static File Service).

# Send a real-time message via Connection Gateway

curl -X POST "http://localhost:8090/message/send/user/12345" \
     -H "Authorization: Bearer <jwt>" \
     -H "Content-Type: application/json" \
     -d '{"message_type":"text","message":"Hello from Macro!"}'

# Generate a presigned upload URL via Static File Service

curl -X PUT "http://localhost:8091/api/file/presigned_url" \
     -H "Authorization: Bearer <jwt>" \
     -H "Content-Type: application/json" \
     -d '{"file_name":"report.pdf","mime_type":"application/pdf"}'

# Convert a document to PDF

curl -X POST "http://localhost:8092/convert" \
     -H "Authorization: Bearer <jwt>" \
     -F "file=@contract.docx"

# Generate AI preview for a document

curl -X POST "http://localhost:8093/preview" \
     -H "Authorization: Bearer <jwt>" \
     -H "Content-Type: application/json" \
     -d '{"document_id":"doc_abc123"}'

# Unfurl a URL for rich preview generation

curl -G "http://localhost:8094/unfurl/http://example.com/article" \
     -H "Authorization: Bearer <jwt>"

API Structure and Conventions

The Macro Inc codebase follows consistent patterns across all services:

• Router Composition: Each service defines a pub fn router() -> Router that composes sub-routers using Axum’s .nest() method.
• Swagger Documentation: Services mount SwaggerUi at /docs using utoipa_swagger_ui, providing interactive API documentation.
• Service Ports: Individual binaries bind to distinct ports (configured via Config structs), allowing independent deployment of the Connection Gateway, Static File Service, and Document Storage Service.
• Internal vs. External: The Static File Service explicitly separates /api (public) and /internal (private) route trees to enforce network-level access controls.

Summary

• Macro Inc API endpoints are organized into domain-specific microservices (Connection Gateway, Static File Service, Document Storage, etc.) written in Rust using Axum.
• WebSocket connections initiate at GET / on the Connection Gateway, while RESTful operations span file management, document conversion, email processing, and AI cognition.
• Authentication is centralized via MacroAuthorizationExtractor with JWT validation, and OpenAPI documentation is automatically served at /docs on each service.
• Source code for routing logic resides in src/api/mod.rs files within each service directory, with explicit line references (e.g., lines 19-25 for Connection Gateway) marking router construction.

Frequently Asked Questions

How do I establish a WebSocket connection to Macro Inc?

Send a GET request to the root path (/) of the Connection Gateway service with the Upgrade: websocket header. The ws_handler function in [services/connection_gateway/src/api/connection/mod.rs](https://github.com/macro-inc/macro/blob/main/services/connection_gateway/src/api/connection/mod.rs) manages the handshake and maintains the persistent connection for real-time messaging.

What is the difference between /api and /internal routes in the Static File Service?

The /api prefix exposes public endpoints for client applications to upload, download, and manage files via presigned URLs. The /internal prefix hosts service-to-service endpoints that skip external authentication and are intended for other microservices within the Macro infrastructure to perform bulk operations or metadata queries.

Where can I find the OpenAPI specification for Macro Inc APIs?

Each microservice mounts a Swagger UI interface at the /docs path (or /api/docs for the Static File Service). These interfaces are generated from inline utoipa annotations in the Rust source code, specifically within the router definitions found in src/api/mod.rs files across the services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}