# Comprehensive Guide to Macro Inc API Endpoints and Interfaces

> Explore Macro Inc API endpoints and interfaces. Discover our Axum-based HTTP and WebSocket services, unified Swagger docs at /docs, and individual service ports. Get started today.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: api-reference
- Published: 2026-08-20

---

**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`](https://github.com/macro-inc/macro/blob/main/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)](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)](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)](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)](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)](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)](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)](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)](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)](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)](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).

```bash

# 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!"}'

```

```bash

# 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"}'

```

```bash

# Convert a document to PDF

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

```

```bash

# 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"}'

```

```bash

# 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`](https://github.com/macro-inc/macro/blob/main/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)](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`](https://github.com/macro-inc/macro/blob/main/src/api/mod.rs) files across the services.