> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Artos API for document generation, template management, and search

# Artos API Documentation

Welcome to the Artos API documentation. Artos is a platform for generating Medical and Regulatory documents using structured templates. The API enables document generation, template management, content search, and document organization.

## Overview

The Artos API provides a RESTful interface for template-based document generation. It enables organizations to:

* **Generate documents asynchronously** by extracting content from source documents and applying templates
* **Manage 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 document outlines** with fine-grained control over sections and extraction rules

## Core Capabilities

### 1. Document Generation

Generate professional documents from source materials using predefined templates. The process is asynchronous and handles document extraction, content ingestion, and orchestrated template application.

```bash theme={null}
POST /api/v1/documents/generate
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "document_type": "CSR",
  "file_paths": ["org-id/documents/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 templates with nested sections and content extraction rules. Templates define the structure and content requirements for generated documents.

```bash theme={null}
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.

```bash theme={null}
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 (returns presigned URLs)
GET /api/v1/files/{container}

# Optional backend proxy for presigned URLs
GET /api/v1/proxy/file?presigned_url={URL_ENCODED_PRESIGNED_URL}
```

## API Resource Groups

The API is organized into 6 resource groups:

| Resource             | Path                    | Purpose                             |
| -------------------- | ----------------------- | ----------------------------------- |
| **Files**            | `/api/v1/files`         | Upload and list S3 files            |
| **Documents**        | `/api/v1/documents`     | Generate documents and check status |
| **Document Sets**    | `/api/v1/document-sets` | Organize documents into sets        |
| **Templates**        | `/api/v1/templates`     | Create and manage templates         |
| **Outlines**         | `/api/v1/mrt-outlines`  | Manage document outlines            |
| **Document Details** | `/api/v1/document-mrt`  | Update document-specific details    |

## Authentication

Most endpoints require Bearer token authentication. Public exceptions are `/api/v1/search/status` and `GET /api/v1/proxy/file`:

```bash theme={null}
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](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 user email
* **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:

```json theme={null}
{
  "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

* **[Authentication](authentication)**: Detailed auth configuration and examples
* **[Files API](files)**: Upload and retrieve documents
* **[Documents API](documents)**: Generate and manage documents
* **[Templates API](templates)**: Create and organize templates
* **[Search API](search)**: Query content across documents
* **[Error Handling](errors)**: Understand error responses