ReportRoom

https://docs.reportroom.io
Admin
ReportRoom is a publishing layer and MCP server that enables AI agents to publish markdown decks or...
Tokens:7,196
Snippets:100
Trust Score:3.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Publish Document Request Examples

Source: https://docs.reportroom.io/

Examples of JSON payloads for publishing documents using either HTML (Mode A) or structured content (Mode B).

```json
Request (Mode A): { "html": "<!doctype html>…", "slug": "acme-pitch", "title": "Acme" }
```

```json
Request (Mode B): { "content": "# Title\n\nBody\n\n---\n\n## Slide 2",
                    "content_format": "markdown", "type": "deck", "slug": "acme-pitch", "theme": "vibrant" }
```

--------------------------------

### GET /oauth/authorize

Source: https://docs.reportroom.io/

Initiates the Authorization Code flow with PKCE.

```APIDOC
## GET /oauth/authorize

### Description
Initiates the OAuth 2.1 Authorization Code flow with PKCE (S256).

### Method
GET

### Endpoint
/oauth/authorize
```

--------------------------------

### GET /v1/handle

Source: https://docs.reportroom.io/

Returns your current handle and URL base.

```APIDOC
## GET /v1/handle

### Description
Returns your current handle (subdomain) and its URL base.

### Method
GET

### Endpoint
/v1/handle
```

--------------------------------

### Quickstart API Usage

Source: https://docs.reportroom.io/

Commands for signing up and publishing a markdown document via the REST API.

```bash
# 1. get an API key (shown once)
curl -sX POST https://api.reportroom.io/v1/signup \
  -H 'content-type: application/json' -d '{"email":"you@example.com"}'

# 2. verify your email — click the link we send you. Publishing is blocked until you do.

# 3. publish a markdown deck
curl -sX POST https://api.reportroom.io/v1/documents \
  -H "authorization: Bearer rr_live_..." -H 'content-type: application/json' \
  -d '{"content":"# Hello\n\nMy first **deck**.","content_format":"markdown","type":"deck","slug":"hello"}'
```

--------------------------------

### Signup Request and Response

Source: https://docs.reportroom.io/

Example request and response structure for the account creation endpoint.

```json
Request:  { "email": "you@example.com", "name": "Optional" }
Response: { "data": { "user_id": "usr_…", "org_id": "org_…",
                      "api_key": "rr_live_…", "tier": "unverified", "message": "…" } }
```

--------------------------------

### Export Document to PDF

Source: https://docs.reportroom.io/

Example cURL command to export a live document to a PDF file.

```bash
curl -X POST https://api.reportroom.io/v1/documents/acme-pitch/export \
  -H "authorization: Bearer rr_live_..." \
  -H "Idempotency-Key: my-export-1" -o acme-pitch.pdf
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://docs.reportroom.io/

Retrieves authorization-server metadata as defined in RFC 8414.

```APIDOC
## GET /.well-known/oauth-authorization-server

### Description
Retrieves authorization-server metadata for OAuth discovery.

### Method
GET

### Endpoint
/.well-known/oauth-authorization-server
```

--------------------------------

### GET /v1/verify

Source: https://docs.reportroom.io/llms.txt

Verifies an account email address to unlock publishing capabilities.

```APIDOC
## GET /v1/verify

### Description
Verifies the account email address using a token sent via email.

### Method
GET

### Endpoint
/v1/verify

### Parameters
#### Query Parameters
- **token** (string) - Required - The verification token.
```

--------------------------------

### GET /v1/documents

Source: https://docs.reportroom.io/

List the account's published documents.

```APIDOC
## GET /v1/documents

### Description
List the account's published documents.

### Method
GET

### Endpoint
/v1/documents

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of documents to return (default 20).
```

--------------------------------

### Get Account Handle Response

Source: https://docs.reportroom.io/

The response structure containing the current account handle and URL base.

```json
Response: { "data": { "handle": "acme", "url_base": "https://acme.reportroom.io" } }
```

--------------------------------

### GET /.well-known/oauth-protected-resource

Source: https://docs.reportroom.io/

Retrieves protected-resource metadata as defined in RFC 9728.

```APIDOC
## GET /.well-known/oauth-protected-resource

### Description
Retrieves protected-resource metadata for OAuth discovery.

### Method
GET

### Endpoint
/.well-known/oauth-protected-resource
```

--------------------------------

### GET /v1/documents/{slug}/analytics

Source: https://docs.reportroom.io/

Retrieve per-document view statistics.

```APIDOC
## GET /v1/documents/{slug}/analytics

### Description
Per-document view stats and a summary.

### Method
GET

### Endpoint
/v1/documents/{slug}/analytics

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the document.
```

--------------------------------

### GET /v1/documents/<slug>/analytics

Source: https://docs.reportroom.io/llms.txt

Retrieves 7-day view analytics for a document.

```APIDOC
## GET /v1/documents/<slug>/analytics

### Description
Returns 7-day view statistics and a summary for the specified document.
```

--------------------------------

### create_account

Source: https://docs.reportroom.io/

Bootstrap a free account. Returns an API key which is shown only once.

```APIDOC
## create_account

### Description
Bootstrap a free account. Returns an API key which is shown only once.

### Authentication
No authentication required.
```

--------------------------------

### POST /v1/signup

Source: https://docs.reportroom.io/llms.txt

Registers a new account and returns an API key.

```APIDOC
## POST /v1/signup

### Description
Registers a new account using an email address.

### Method
POST

### Endpoint
/v1/signup

### Request Body
- **email** (string) - Required - The email address for the new account.
```

--------------------------------

### POST /v1/signup

Source: https://docs.reportroom.io/

Create a new account to receive an API key. This endpoint is rate-limited and requires email verification before publishing is enabled.

```APIDOC
## POST /v1/signup

### Description
Create a free account and receive an API key. The key is shown only once.

### Method
POST

### Endpoint
/v1/signup

### Request Body
- **email** (string) - Required - The user's email address.
- **name** (string) - Optional - The user's name.

### Response
#### Success Response (200)
- **user_id** (string) - Unique identifier for the user.
- **org_id** (string) - Unique identifier for the organization.
- **api_key** (string) - The API key for authentication.
- **tier** (string) - The account verification status.
- **message** (string) - Status message.
```

--------------------------------

### create_data_room

Source: https://docs.reportroom.io/

Create a room to share documents behind a gate.

```APIDOC
## create_data_room

### Description
Create a room (name, slug) to share documents behind a gate.

### Authentication
Yes
```

--------------------------------

### Configure Codex CLI for ReportRoom

Source: https://docs.reportroom.io/

Configuration settings and login command for integrating the ReportRoom MCP server with the Codex CLI.

```toml
[mcp_servers.reportroom]
url = "https://mcp.reportroom.io/mcp"
# optional — API key instead of OAuth:
# bearer_token_env_var = "REPORTROOM_KEY"
```

```bash
codex mcp login reportroom   # OAuth sign-in
# verify with /mcp in the Codex TUI
```

--------------------------------

### POST /v1/documents

Source: https://docs.reportroom.io/

Publish a markdown deck or report to a live URL.

```APIDOC
## POST /v1/documents

### Description
Publishes a markdown-formatted document to a unique slug under the user's handle.

### Method
POST

### Endpoint
/v1/documents

### Request Body
- **content** (string) - Required - The markdown content of the document.
- **content_format** (string) - Required - The format of the content (e.g., 'markdown').
- **type** (string) - Required - The type of document (e.g., 'deck').
- **slug** (string) - Required - The unique identifier for the document URL.
```

--------------------------------

### Add MCP Connector via CLI

Source: https://docs.reportroom.io/llms.txt

Command to register the ReportRoom MCP server using the Claude CLI.

```bash
claude mcp add --transport http reportroom https://mcp.reportroom.io/mcp ; call create_account, verify the email, then publish
```

--------------------------------

### POST /v1/handle

Source: https://docs.reportroom.io/

Rename your subdomain. This moves all documents to the new handle and sets up redirects for old links.

```APIDOC
## POST /v1/handle

### Description
Rename your subdomain. Moves all your docs to the new handle; old links redirect. Requires auth.

### Method
POST

### Endpoint
/v1/handle

### Request Body
- **handle** (string) - Required - The new handle for the subdomain.

### Request Example
{
  "handle": "acme"
}

### Response
#### Success Response (200)
- **data** (object) - Contains the new handle, move count, and status message.
```

--------------------------------

### POST /oauth/register

Source: https://docs.reportroom.io/

Performs dynamic client registration as defined in RFC 7591.

```APIDOC
## POST /oauth/register

### Description
Registers a new client dynamically.

### Method
POST

### Endpoint
/oauth/register
```

--------------------------------

### POST /v1/lint

Source: https://docs.reportroom.io/

Pre-flight check an HTML document before publishing.

```APIDOC
## POST /v1/lint

### Description
Pre-flight check an HTML document before publishing (checks for missing viewport/og tags, stripped scripts, etc.). No auth required.

### Method
POST

### Endpoint
/v1/lint

### Request Body
- **html** (string) - Required - The HTML content to validate.

### Request Example
{
  "html": "<!doctype html>…"
}

### Response
#### Success Response (200)
- **data** (object) - Contains validation status and list of issues.
```

--------------------------------

### Connect Claude Code to ReportRoom

Source: https://docs.reportroom.io/

Commands to register the ReportRoom MCP server with Claude Code, including optional API key authentication.

```bash
claude mcp add --transport http reportroom https://mcp.reportroom.io/mcp
# in a session:
#   1) call create_account (email) -> save the api_key
#   2) re-add with the key:
claude mcp add --transport http reportroom https://mcp.reportroom.io/mcp \
  --header "Authorization: Bearer rr_live_..."
```

--------------------------------

### export_pdf

Source: https://docs.reportroom.io/

Render a live document to a print-quality PDF.

```APIDOC
## export_pdf

### Description
Render a live document to a print-quality PDF (5 credits). Idempotency key makes retries charge once. Returns a signed download URL valid for 1 hour.

### Authentication
Yes
```

--------------------------------

### POST /v1/documents/{slug}/republish

Source: https://docs.reportroom.io/

Bring a previously-unpublished document back live.

```APIDOC
## POST /v1/documents/{slug}/republish

### Description
Bring a previously-unpublished document back live. Re-checks the email gate and plan quota.

### Method
POST

### Endpoint
/v1/documents/{slug}/republish

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the document to republish.
```

--------------------------------

### Publish Document via REST API

Source: https://docs.reportroom.io/llms.txt

Sequence of REST API calls to sign up, verify, and publish a document.

```http
POST /v1/signup {email} -> api_key ; verify email ; POST /v1/documents {content, content_format:"markdown", type:"deck", slug} with Authorization: Bearer -> url https://<handle>.reportroom.io/<slug>
```

--------------------------------

### POST /v1/documents

Source: https://docs.reportroom.io/mcp.md

Publish or update a document. Idempotent on slug.

```APIDOC
## POST /v1/documents

### Description
Publish or update a document. Idempotent on `slug` — reuse a slug to update in place. Requires auth. Provide either `html` (Mode A) or `content` + `content_format` + `type` (Mode B).

### Method
POST

### Endpoint
/v1/documents

### Request Example
Mode A:
{ "html": "<!doctype html>…", "slug": "acme-pitch", "title": "Acme" }

Mode B:
{ "content": "# Title\n\nBody\n\n---\n\n## Slide 2", "content_format": "markdown", "type": "deck", "slug": "acme-pitch", "theme": "vibrant" }

### Response
#### Success Response (200)
- **data** (object) - Contains document details including url, documentId, slug, version, chartsRendered, chartErrors, artifactKey, visibility, status, scan, removalsCount, and message.
```

--------------------------------

### POST /v1/documents

Source: https://docs.reportroom.io/mcp.md

Publishes a markdown-formatted document to the user's account. Requires a verified account and a valid bearer token.

```APIDOC
## POST /v1/documents

### Description
Publishes a markdown deck or report. Publishing is blocked until the account email is verified.

### Method
POST

### Endpoint
/v1/documents

### Request Body
- **content** (string) - Required - The markdown content of the document.
- **content_format** (string) - Required - The format of the content (e.g., 'markdown').
- **type** (string) - Required - The type of document (e.g., 'deck').
- **slug** (string) - Required - The unique identifier for the document within the account.
```

--------------------------------

### Verification Response

Source: https://docs.reportroom.io/

Expected JSON response after successfully verifying an account.

```json
Response: { "data": { "tier": "verified", "migrated": [], "message": "…" } }
```

--------------------------------

### POST /v1/documents/{slug}/unpublish

Source: https://docs.reportroom.io/

Retire one of your live documents.

```APIDOC
## POST /v1/documents/{slug}/unpublish

### Description
Retire one of your live documents: its URL starts returning 410 Gone and the plan slot is freed.

### Method
POST

### Endpoint
/v1/documents/{slug}/unpublish

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the document to unpublish.
```

--------------------------------

### Rename Subdomain

Source: https://docs.reportroom.io/

Updates the workspace handle. Existing links will redirect to the new handle.

```json
Request:  { "handle": "acme" }
Response: { "data": { "handle": "acme", "moved": 3, "message": "…" } }
```

--------------------------------

### Manage Workspace Branding

Source: https://docs.reportroom.io/

Sets or retrieves the workspace logo. The image must be owned by the user, marked as a brand, and set to public visibility.

```json
PUT request:  { "image_id": "img_…" }   // must be YOUR image with kind=brand and visibility=public
GET response: { "data": { "logo": { "image_id": "img_…", "path": "/_img/…", "url": "https://…" } } }
```

--------------------------------

### POST /v1/images

Source: https://docs.reportroom.io/llms.txt

Uploads an image to be referenced in documents.

```APIDOC
## POST /v1/images

### Description
Uploads an image file (max 2MB) to generate a content-addressed path.
```

--------------------------------

### publish

Source: https://docs.reportroom.io/

Publish or update a deck or report. Idempotent on slug. Requires a verified email.

```APIDOC
## publish

### Description
Publish or update a deck or report. Supports Mode A (html) or Mode B (content + type). Idempotent on slug. Requires a verified email.

### Authentication
Requires a verified email.
```

--------------------------------

### POST /v1/documents/<slug>/export

Source: https://docs.reportroom.io/llms.txt

Exports a document to a print-quality PDF.

```APIDOC
## POST /v1/documents/<slug>/export

### Description
Generates a PDF export for the specified document slug. Costs 5 credits.
```

--------------------------------

### Upload Image

Source: https://docs.reportroom.io/

Returns metadata for a successfully uploaded image. Images are subject to a 2MB size limit and magic-byte validation.

```json
Response 201: { "data": { "id": "img_…", "url": "https://acme.reportroom.io/_img/org_…/<sha256>.png",
                          "path": "/_img/org_…/<sha256>.png", "kind": "doc", "visibility": "public",
                          "sha256": "…", "bytes": 12345, "content_type": "image/png", "deduped": false } }
```

--------------------------------

### POST /v1/documents

Source: https://docs.reportroom.io/llms.txt

Publishes a new document or updates an existing one.

```APIDOC
## POST /v1/documents

### Description
Publishes content as a deck or report. Requires an authorized Bearer token.

### Method
POST

### Endpoint
/v1/documents

### Request Body
- **content** (string) - Required - The document content (markdown or HTML).
- **content_format** (string) - Required - Format of the content (e.g., "markdown").
- **type** (string) - Required - Type of document (e.g., "deck").
- **slug** (string) - Required - Unique identifier for the document.
```

--------------------------------

### POST /oauth/token

Source: https://docs.reportroom.io/

Exchanges authorization codes or refresh tokens for access tokens.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code or refresh token for an access token.

### Method
POST

### Endpoint
/oauth/token
```

--------------------------------

### upload_image

Source: https://docs.reportroom.io/

Upload base64 image bytes (PNG/JPEG/WebP/GIF, 2 MB max).

```APIDOC
## upload_image

### Description
Upload base64 image bytes (PNG/JPEG/WebP/GIF, 2 MB max, plan caps). Use kind=brand for a logo, visibility=team for members-only.

### Authentication
Yes
```

--------------------------------

### POST /v1/report-abuse

Source: https://docs.reportroom.io/

Report an abusive published page.

```APIDOC
## POST /v1/report-abuse

### Description
Report an abusive published page. No auth required, rate-limited.

### Method
POST

### Endpoint
/v1/report-abuse

### Request Body
- **url** (string) - Required - The URL of the abusive page.
- **reason** (string) - Required - The reason for the report.

### Request Example
{
  "url": "https://bad-handle.reportroom.io/bad-slug",
  "reason": "phishing"
}
```

--------------------------------

### Lint HTML Document

Source: https://docs.reportroom.io/

Validates HTML content for publishing requirements. No authentication is required.

```json
Request:  { "html": "<!doctype html>…" }
Response: { "data": { "ok": true, "issues": [ { "level": "warning", "code": "no-og-title", "message": "…" } ] } }
```

--------------------------------

### Republish Document Response

Source: https://docs.reportroom.io/

The response structure returned after successfully bringing a document back live.

```json
Response: { "data": { "slug": "acme-pitch", "status": "live" } }
```

--------------------------------

### Publish Document Response

Source: https://docs.reportroom.io/

The response structure returned after a successful document publish operation.

```json
Response: { "data": { "url": "https://acme.reportroom.io/acme-pitch", "documentId": "doc_…",
                      "slug": "acme-pitch", "version": 1, "chartsRendered": 1, "chartErrors": [],
                      "artifactKey": "…", "visibility": "public", "status": "live",
                      "scan": { "verdict": "clean", "score": 0, "reasons": [] },
                      "removalsCount": 0, "message": "…" } }
```

--------------------------------

### API Authentication Header

Source: https://docs.reportroom.io/

Format for the Authorization header required by most API endpoints.

```http
Authorization: Bearer rr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Unpublish Document Response

Source: https://docs.reportroom.io/

The response structure returned after successfully retiring a live document.

```json
Response: { "data": { "slug": "acme-pitch", "status": "unpublished" } }
```

--------------------------------

### Report Abusive Content

Source: https://docs.reportroom.io/

Submits a report for an abusive published page. This endpoint is rate-limited and does not require authentication.

```json
Request: { "url": "https://bad-handle.reportroom.io/bad-slug", "reason": "phishing" }
```

--------------------------------

### Document Analytics Response

Source: https://docs.reportroom.io/

The response structure containing view statistics for a specific document.

```json
Response: { "data": { "slug": "acme-pitch", "url": "https://acme.reportroom.io/acme-pitch",
                      "views7d": 42, "byDay": [{ "day": "2026-07-05", "views": 8 }, …],
                      "message": "\"Acme\" got 42 views in the last 7 days…" } }
```
Tokens:
Raw