API Reference

Rosetta provides a RESTful API for programmatic access to core functionality. This enables integration with EMR systems, custom tooling, and automation workflows.

Beta API: The Rosetta API is currently in beta. Breaking changes may occur. We’ll provide migration guides for any breaking changes.

Authentication

API Keys

API access requires an API key:

Navigate to Settings → API Keys
Click “Generate New API Key”
Copy and securely store your key (shown only once)
Include in requests via Authorization header

Example:


curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://philipshih.org/apps/rosetta/api/v1/documents

Security Best Practices

Never commit API keys to version control
Rotate keys regularly (every 90 days)
Use separate keys for different applications
Revoke compromised keys immediately
Store securely using environment variables or secret managers

Base URL


https://philipshih.org/apps/rosetta/api/v1

All API requests use HTTPS. HTTP requests are automatically upgraded.

Rate Limiting

To ensure service quality, API requests are rate-limited:

Tier	Limit	Burst
Free	100 requests/hour	10 concurrent
Professional	1,000 requests/hour	50 concurrent
Enterprise	10,000 requests/hour	100 concurrent

Rate Limit Headers:


X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1640000000

429 Too Many Requests:


{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 3600 seconds.",
  "retry_after": 3600
}

Common Headers

Request Headers


Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-Request-ID: unique-request-id (optional, for debugging)

Response Headers


Content-Type: application/json
X-Request-ID: unique-request-id
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987

Endpoints

Documents

List Documents

Retrieve paginated list of documents.


GET /v1/documents

Query Parameters:

Parameter	Type	Description
`limit`	integer	Results per page (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)
`sort`	string	Sort field (`created_at`, `updated_at`, `title`)
`order`	string	Sort order (`asc` or `desc`)
`search`	string	Full-text search query
`tag`	string	Filter by tag

Example Request:


curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://philipshih.org/apps/rosetta/api/v1/documents?limit=10&sort=created_at&order=desc"

Example Response:


{
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Progress Note - Patient A",
      "content": "...",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T11:45:00Z",
      "tags": ["progress-note", "cardiology"],
      "template_id": "tpl_123",
      "metadata": {
        "document_type": "progress_note",
        "date_of_service": "2026-01-15"
      }
    }
  ],
  "pagination": {
    "total": 145,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Document

Retrieve a specific document by ID.


GET /v1/documents/:id

Example Request:


curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://philipshih.org/apps/rosetta/api/v1/documents/doc_abc123

Example Response:


{
  "id": "doc_abc123",
  "title": "Progress Note - Patient A",
  "content": "Full document content in markdown format...",
  "content_html": "<p>Full document content in HTML...</p>",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T11:45:00Z",
  "tags": ["progress-note", "cardiology"],
  "template_id": "tpl_123",
  "metadata": {
    "document_type": "progress_note",
    "date_of_service": "2026-01-15",
    "word_count": 450,
    "character_count": 2800
  }
}

Create Document

Create a new document.


POST /v1/documents

Request Body:


{
  "title": "New Progress Note",
  "content": "Document content in markdown...",
  "tags": ["progress-note"],
  "template_id": "tpl_123",
  "metadata": {
    "document_type": "progress_note",
    "date_of_service": "2026-01-20"
  }
}

Example Request:


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Note","content":"Content here..."}' \
  https://philipshih.org/apps/rosetta/api/v1/documents

Example Response:


{
  "id": "doc_xyz789",
  "title": "New Progress Note",
  "content": "Document content in markdown...",
  "created_at": "2026-01-20T09:15:00Z",
  "updated_at": "2026-01-20T09:15:00Z"
}

Update Document

Update an existing document.


PATCH /v1/documents/:id

Request Body:


{
  "title": "Updated Title",
  "content": "Updated content...",
  "tags": ["progress-note", "updated"]
}

Example Request:


curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated Title"}' \
  https://philipshih.org/apps/rosetta/api/v1/documents/doc_abc123

Delete Document

Delete a document (moves to trash).


DELETE /v1/documents/:id

Example Request:


curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://philipshih.org/apps/rosetta/api/v1/documents/doc_abc123

Example Response:


{
  "success": true,
  "message": "Document moved to trash",
  "recoverable_until": "2026-02-19T09:15:00Z"
}

Templates

List Templates

Retrieve available templates.


GET /v1/templates

Example Response:


{
  "templates": [
    {
      "id": "tpl_hp001",
      "name": "History & Physical",
      "description": "Complete H&P template",
      "category": "inpatient",
      "content": "# History & Physical\n\n## Chief Complaint\n...",
      "placeholders": [
        {"name": "chief_complaint", "type": "text"},
        {"name": "hpi", "type": "textarea"}
      ]
    }
  ]
}

Get Template

Retrieve specific template.


GET /v1/templates/:id

AI Assistant

Ask Question

Query the RAG-powered AI assistant.


POST /v1/ai/ask

Request Body:


{
  "question": "What is the treatment for community-acquired pneumonia?",
  "context": "Outpatient, no comorbidities",
  "include_citations": true
}

PHI Protection: Ensure no PHI is included in API queries. The system will automatically redact detected PHI, but it’s best practice to avoid sending it.

Example Response:


{
  "answer": "For a previously healthy adult with community-acquired pneumonia (CAP)...",
  "confidence": 0.95,
  "citations": [
    {
      "title": "IDSA/ATS CAP Guidelines (2019)",
      "url": "https://www.idsociety.org/...",
      "relevance_score": 0.98
    }
  ],
  "evidence_grade": "high",
  "usage": {
    "tokens": 350,
    "cost": 0.0012
  }
}

Generate Text

Generate or expand text with AI.


POST /v1/ai/generate

Request Body:


{
  "prompt": "Expand on COPD exacerbation",
  "context": "Progress note, moderate severity",
  "max_tokens": 500,
  "temperature": 0.7
}

Export

Export Document

Export document in various formats.


POST /v1/documents/:id/export

Request Body:


{
  "format": "pdf",
  "options": {
    "include_metadata": true,
    "include_citations": true,
    "page_size": "letter",
    "orientation": "portrait"
  }
}

Supported Formats:

pdf - PDF document
docx - Microsoft Word
html - HTML document
txt - Plain text
markdown - Markdown format

Example Response:


{
  "export_id": "exp_abc123",
  "status": "completed",
  "download_url": "https://philipshih.org/apps/rosetta/api/v1/exports/exp_abc123/download",
  "expires_at": "2026-01-20T12:00:00Z"
}

Error Handling

Error Response Format

All errors follow a consistent format:


{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "title",
        "issue": "Title is required"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Successful request
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)

Error Types

Type	Description
`authentication_error`	Invalid or missing API key
`validation_error`	Invalid request parameters
`permission_error`	Insufficient permissions
`rate_limit_error`	Rate limit exceeded
`not_found_error`	Resource not found
`server_error`	Internal server error

Webhooks

Subscribe to events in your Rosetta account.

Available Events

document.created - New document created
document.updated - Document modified
document.deleted - Document deleted
export.completed - Export finished
ai.query_completed - AI query finished

Webhook Configuration

Configure webhooks in Settings → Webhooks.

Webhook Payload Example:


{
  "event": "document.created",
  "timestamp": "2026-01-20T10:30:00Z",
  "data": {
    "document_id": "doc_abc123",
    "title": "New Progress Note"
  }
}

SDKs and Libraries

Official SDKs

Python:


pip install rosetta-client


from rosetta import RosettaClient
 
client = RosettaClient(api_key="YOUR_API_KEY")
documents = client.documents.list(limit=10)

JavaScript/TypeScript:


npm install @rosetta/client


import { RosettaClient } from '@rosetta/client';
 
const client = new RosettaClient({ apiKey: 'YOUR_API_KEY' });
const documents = await client.documents.list({ limit: 10 });

Community Libraries

Ruby: rosetta-ruby
Go: go-rosetta
PHP: rosetta-php

Code Examples

Create and Export Document

Python:


from rosetta import RosettaClient
 
client = RosettaClient(api_key="YOUR_API_KEY")
 
# Create document
doc = client.documents.create(
    title="Progress Note",
    content="Patient presents with...",
    template_id="tpl_progress_note"
)
 
# Export to PDF
export = client.documents.export(
    doc.id,
    format="pdf",
    options={"include_metadata": True}
)
 
print(f"Download: {export.download_url}")

JavaScript:


const { RosettaClient } = require('@rosetta/client');
 
const client = new RosettaClient({ apiKey: 'YOUR_API_KEY' });
 
async function createAndExport() {
  // Create document
  const doc = await client.documents.create({
    title: 'Progress Note',
    content: 'Patient presents with...',
    templateId: 'tpl_progress_note'
  });
 
  // Export to PDF
  const exportResult = await client.documents.export(doc.id, {
    format: 'pdf',
    options: { includeMetadata: true }
  });
 
  console.log(`Download: ${exportResult.downloadUrl}`);
}
 
createAndExport();

Ask AI Assistant

Python:


response = client.ai.ask(
    question="Treatment for CAP in healthy adults?",
    include_citations=True
)
 
print(f"Answer: {response.answer}")
print(f"Confidence: {response.confidence}")
for citation in response.citations:
    print(f"Source: {citation.title}")

cURL:


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Treatment for CAP in healthy adults?",
    "include_citations": true
  }' \
  https://philipshih.org/apps/rosetta/api/v1/ai/ask

API Changelog

v1.0.0 (Current)

Initial public API release
Documents, templates, AI assistant endpoints
Export functionality
Webhook support

Upcoming Features

Batch operations
Advanced search filters
Real-time collaboration API
Template management endpoints

Need Help?