Skip to main content

​
Artos API Documentation

Welcome to the Artos API documentation. Artos is a platform for generating Medical and Regulatory documents using MRT (Machine Readable Template) technology. The API enables document generation, template management, content search, and document organization.

​
Overview

The Artos API provides a RESTful interface for working with MRT-based document generation. It enables organizations to:
  • Generate documents asynchronously by extracting content from source documents and applying MRT templates
  • Manage MRT templates with nested sections and extraction rules
  • Organize documents into document sets for collaborative work
  • Search content using hybrid search combining vector similarity and full-text search
  • Update MRT structures with fine-grained control over sections and extraction rules

​
Core Capabilities

​
1. Document Generation

Generate professional documents from source materials using predefined MRT templates. The process is asynchronous and handles document extraction, content ingestion, and orchestrated template application. 
POST /api/v1/documents/generate
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "document_type": "CSR",
  "file_paths": ["s3://bucket/input.docx"],
  "document_set_key": "project-2024-001",
  "document_set_name": "Q1 CSR Documents",
  "generic_mrt_id": "template-uuid-123",
  "output_name": "CSR_Final.docx"
}

# Response (202 Accepted)
{
  "message": "Document generation started",
  "task_id": "task-uuid-456"
}

# Poll status
GET /api/v1/documents/status/document-uuid

​
2. Template Management

Create and manage MRT templates with nested sections and content extraction rules. Templates define the structure and content requirements for generated documents. 
POST /api/v1/templates/
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "template_name": "CSR Template",
  "document_type": "CSR",
  "sections": [
    {
      "order_index": 0,
      "level": 1,
      "section_name": "Executive Summary",
      "template_instructions": "Summarize key findings",
      "rules": [...]
    }
  ]
}

# Get templates
GET /api/v1/templates/
GET /api/v1/templates/{template_id}

​
3. File Management

Upload source documents and access generated files using S3 with presigned URLs. 
POST /api/v1/files/upload
Content-Type: multipart/form-data
Authorization: Bearer YOUR_TOKEN

file_name: "protocol.pdf"
file_content: <binary>
container: "documents"

# List files
GET /api/v1/files/{container}
Search across MRT example chunks using a combination of vector similarity (pgvector) and full-text search (tsvector). 
POST /api/v1/search/hybrid-test
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "document_set_key": "project-key",
  "query": "safety findings",
  "limit": 20,
  "document_filters": ["Protocol*"]
}

​
API Resource Groups

The API is organized into 7 resource groups:
ResourcePathPurpose
Files/api/v1/filesUpload and list S3 files
Documents/api/v1/documentsGenerate documents and check status
Document Sets/api/v1/document-setsOrganize documents into sets
Templates/api/v1/templatesCreate and manage MRT templates
MRT Outlines/api/v1/mrt-outlinesManage document outlines
Document MRT/api/v1/document-mrtUpdate document-specific MRT details
Search/api/v1/searchSearch across content using hybrid search

​
Authentication

All endpoints (except /api/v1/search/status) require Bearer token authentication: 
curl -X GET https://api.artosai.com/api/v1/templates/ \
  -H "Authorization: Bearer YOUR_TOKEN"
The Bearer token provides:
  • User identification for operation tracking
  • Organization scoping for multi-tenant data access
  • Permission validation for resource ownership
See Authentication for detailed information.

​
Document Generation Flow

The typical workflow for generating a document: 
1. Create document set (if needed)
   POST /api/v1/document-sets/

2. Upload source documents
   POST /api/v1/files/upload

3. Request document generation (returns 202 Accepted)
   POST /api/v1/documents/generate

4. Poll generation status
   GET /api/v1/documents/status/{document_id}

5. Retrieve completed document
   GET /api/v1/documents/{document_id}

6. Download generated file
   GET /api/v1/files/{container}
   (retrieve presigned URL and download via S3)

​
Async Processing Pattern

Document generation uses asynchronous processing via Celery:
  • POST returns 202 Accepted with a task_id for immediate feedback
  • Status polling allows clients to track progress
  • Completion notification sent via email to [email protected]
  • No webhooks currently available (use polling instead)

​
Error Handling

All endpoints return standard HTTP status codes with error details:
  • 200 OK: Successful GET/PUT request
  • 201 Created: Successful POST (resource created)
  • 202 Accepted: Async task queued
  • 400 Bad Request: Validation error or missing required fields
  • 401 Unauthorized: Missing or invalid Bearer token
  • 403 Forbidden: Insufficient permissions or wrong organization
  • 404 Not Found: Resource does not exist
  • 422 Unprocessable Entity: Request validation error
  • 500 Internal Server Error: Server-side processing error
Example error response: 
{
  "detail": "Document not found or not accessible"
}

​
Organization Scoping

All resources are automatically scoped to the authenticated user’s organization. A user’s Bearer token contains their organization context, ensuring:
  • Users can only access their organization’s resources
  • Resources are automatically filtered by organization
  • Cross-organization access is prevented
  • Multi-tenant isolation is enforced

​
Getting Started

  1. Obtain a Bearer token from your organization administrator
  2. Choose a resource you want to work with (files, documents, templates, etc.)
  3. Review the endpoint documentation for request/response formats
  4. Test with curl or Postman to understand the API
  5. Integrate into your application using the SDK or direct HTTP calls

​
Next Steps