Templates API

The Templates API manages templates with nested sections and content extraction rules. Templates define the structure and content requirements for generated documents.

List Templates

Retrieve all templates accessible to the authenticated user, sorted by creation date (newest first).

GET /api/v1/templates/

Request Example

curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "templates": [
    {
      "id": "tmpl-uuid-1",
      "template_name": "CSR Template",
      "source_document_name": "csr-example.docx",
      "url": "https://s3.amazonaws.com/bucket/template.docx?X-Amz-Algorithm=...",
      "detected_document_type": "CSR",
      "template_id": "tmpl-uuid-1",
      "sections": [
        {
          "section_id": "sect-uuid-1",
          "section_name": "1. Executive Summary",
          "order_index": 0,
          "level": 1
        },
        {
          "section_id": "sect-uuid-2",
          "section_name": "2. Study Design",
          "order_index": 1,
          "level": 1
        }
      ],
      "status": "active",
      "template_file_name": "csr-template.docx",
      "created_at": "2024-01-20T10:00:00Z",
      "updated_at": "2024-01-25T12:00:00Z"
    }
  ]
}

Status Codes

200 OK: Templates retrieved successfully
401 Unauthorized: Missing or invalid Bearer token

Get Single Template

Retrieve a specific template with full details including sections, rules, users, and style information.

GET /api/v1/templates/{template_id}

Path Parameters

Parameter	Type	Required	Description
`template_id`	string	Yes	UUID of the template

Request Example

curl -X GET "https://api.artosai.com/api/v1/templates/tmpl-uuid-1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "url": "https://s3.amazonaws.com/bucket/template.docx?X-Amz-Algorithm=...",
  "template_name": "CSR Template",
  "source_document_name": "csr-example.docx",
  "detected_document_type": "CSR",
  "document_type": "CSR",
  "template_id": "tmpl-uuid-1",
  "template_s3_uri": "org-uuid/templates/csr-template.docx",
  "template_file_name": "csr-template.docx",
  "sections": [
    {
      "section_id": "sect-uuid-1",
      "order_index": 0,
      "level": 1,
      "section_name": "1. Executive Summary",
      "synopsis": "Summary of key findings",
      "template_instructions": "Summarize in 2-3 paragraphs",
      "template_text": "This section provides a concise overview...",
      "is_repeating": false,
      "rules": [
        {
          "rule_id": "rule-uuid-1",
          "rule_type": "CopyPasteRule",
          "rule_mode": "auto",
          "description": "Extract safety findings",
          "style_names": ["Normal"],
          "fill": null,
          "color": null
        }
      ]
    }
  ],
  "examples": [
    {
      "example_id": "ex-uuid-1",
      "content": "Example CSR executive summary text..."
    }
  ],
  "all_styles": ["Normal", "Heading 1", "Heading 2", "Table Text"],
  "users": [
    {
      "user_id": "user-uuid-1",
      "email": "alice@example.com"
    }
  ],
  "document_instructions": "Follow ICH E3 guidelines for all sections.",
  "document_metadata": {
    "sponsor": "Acme Pharma",
    "study_number": "ACME-2024-001"
  },
  "hidden_text_style": "Hidden",
  "include_instructions": true
}

Status Codes

200 OK: Template retrieved successfully
400 Bad Request: Authentication failure
404 Not Found: Template not found

Create Template

Create a new template with nested sections and extraction rules.

POST /api/v1/templates/

Request Body

{
  "template_name": "CSR Template",
  "document_type": "CSR",
  "sections": [
    {
      "order_index": 0,
      "level": 1,
      "section_name": "1. Executive Summary",
      "synopsis": "Overview of document findings",
      "template_instructions": "Summarize key findings in 2-3 paragraphs",
      "template_text": "This section provides a concise overview...",
      "section_type": "summary",
      "section_mode": "auto",
      "is_repeating": false,
      "rules": [
        {
          "rule_type": "CopyPasteRule",
          "rule_mode": "auto",
          "description": "Extract safety data"
        }
      ]
    },
    {
      "order_index": 1,
      "level": 1,
      "section_name": "2. Study Design",
      "synopsis": "Description of study methodology",
      "template_instructions": "Describe study design and objectives"
    }
  ],
  "template_s3_uri": "org-id/templates/csr-template.docx",
  "document_description": "Standard CSR template per ICH E3",
  "tags": ["csr", "regulatory"],
  "users": ["user-uuid-1", "user-uuid-2"]
}

Request Parameters

Parameter	Type	Required	Description
`template_name`	string	Yes	Template name
`document_type`	string	Yes	Document type (e.g., `"CSR"`, `"IND"`, `"NDA"`)
`sections`	array	Yes	At least one section required
`template_s3_uri`	string	Required*	S3 URI for the template file
`template_file_name`	string	Required*	Template file name (alternative to `template_s3_uri`)
`document_description`	string	No	Description
`tags`	array	No	Categorization tags
`users`	array	No	User IDs to grant access

* Either template_s3_uri or template_file_name must be provided.

Section Parameters

Parameter	Type	Required	Description
`order_index`	integer	Yes	Position in template (0-based, must be unique)
`level`	integer	Yes	Nesting level (1 = top-level, 2 = subsection, etc.)
`section_name`	string	Yes	Section title
`synopsis`	string	No	Brief summary
`template_instructions`	string	No	Completion instructions
`template_text`	string	No	Template text
`section_type`	string	No	Section type classification
`section_mode`	string	No	Operation mode
`is_repeating`	boolean	No	Default: `false`
`expansion_type`	string	No	For repeating sections
`rules`	array	No	Extraction rules for the section

Request Example

curl -X POST "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "CSR Template",
    "document_type": "CSR",
    "sections": [
      {
        "order_index": 0,
        "level": 1,
        "section_name": "1. Executive Summary",
        "template_instructions": "Summarize findings"
      }
    ],
    "template_s3_uri": "org-id/templates/csr-template.docx"
  }'

Python Example

import requests

url = "https://api.artosai.com/api/v1/templates/"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "template_name": "CSR Template",
    "document_type": "CSR",
    "sections": [
        {
            "order_index": 0,
            "level": 1,
            "section_name": "1. Executive Summary",
            "template_instructions": "Summarize key findings"
        },
        {
            "order_index": 1,
            "level": 1,
            "section_name": "2. Study Design",
            "template_instructions": "Describe study methodology"
        }
    ],
    "template_s3_uri": "org-id/templates/csr-template.docx"
}

response = requests.post(url, headers=headers, json=payload)
template = response.json()
print(f"Created template: {template['template_id']}")
print(f"Sections: {template['section_count']}, Rules: {template['rule_count']}")

Response (201 Created)

{
  "template_id": "tmpl-uuid-789",
  "template_name": "CSR Template",
  "organization_id": "org-uuid-789",
  "section_count": 2,
  "rule_count": 1,
  "created_at": "2024-01-25T12:00:00Z",
  "message": "Template created successfully"
}

Response Fields

Field	Type	Description
`template_id`	string	UUID of the created template
`template_name`	string	Name of the template
`organization_id`	string	Organization UUID
`section_count`	integer	Number of sections created
`rule_count`	integer	Total number of rules across all sections
`created_at`	string	ISO 8601 creation timestamp
`message`	string	Success message

Status Codes

201 Created: Template created successfully
400 Bad Request: Validation errors (missing fields, duplicate order_index, missing template_s3_uri/template_file_name)
401 Unauthorized: Authentication failure
500 Internal Server Error: Database operation failure

Add Section to Template

Add a new section to an existing template.

POST /api/v1/templates/{template_id}/sections

Path Parameters

Parameter	Type	Required	Description
`template_id`	string	Yes	UUID of the template

Request Body

{
  "section_name": "3. Safety Analysis",
  "level": 1,
  "order_index": 2
}

Request Parameters

Parameter	Type	Required	Description
`section_name`	string	Yes	Name/title of the section
`level`	integer	Yes	Nesting level (1 = top-level, 2 = subsection, etc.)
`order_index`	integer	Yes	Position in the template (0-based)

Request Example

curl -X POST "https://api.artosai.com/api/v1/templates/tmpl-uuid-1/sections" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "section_name": "3. Safety Analysis",
    "level": 1,
    "order_index": 2
  }'

Response

{
  "message": "Section added successfully",
  "section_id": "sect-uuid-new",
  "template_id": "tmpl-uuid-1",
  "section_name": "3. Safety Analysis",
  "level": 1,
  "order_index": 2
}

Status Codes

200 OK: Section added successfully
400 Bad Request: Authentication errors
403 Forbidden: Unauthorized access
404 Not Found: Template not found
500 Internal Server Error: Database operation failure

Rename Template Section

Update the name of an existing template section.

PUT /api/v1/templates/{template_id}/sections/{section_id}/rename

Path Parameters

Parameter	Type	Required	Description
`template_id`	string	Yes	UUID of the template
`section_id`	string	Yes	UUID of the section to rename

Request Body

{
  "section_name": "3.1 Adverse Events"
}

Request Parameters

Parameter	Type	Required	Description
`section_name`	string	Yes	New name for the section (e.g., `"2.1 Efficacy Results"`)

Request Example

curl -X PUT "https://api.artosai.com/api/v1/templates/tmpl-uuid-1/sections/sect-uuid-1/rename" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "section_name": "3.1 Adverse Events"
  }'

Response

{
  "section_id": "sect-uuid-1",
  "section_name": "3.1 Adverse Events",
  "message": "Section renamed successfully"
}

Status Codes

200 OK: Section renamed successfully
400 Bad Request: Authentication errors
403 Forbidden: Unauthorized access
404 Not Found: Template or section not found
500 Internal Server Error: Database operation failure

Reorder Template Sections

Reorder and automatically renumber all sections in a template. After reordering, section names are renumbered to reflect the new hierarchy (e.g., "1.", "1.1", "2.").

PUT /api/v1/templates/{template_id}/sections/reorder

Path Parameters

Parameter	Type	Required	Description
`template_id`	string	Yes	UUID of the template

Request Body

{
  "sections": [
    { "section_id": "sect-uuid-2", "order_index": 0, "level": 1 },
    { "section_id": "sect-uuid-1", "order_index": 1, "level": 1 },
    { "section_id": "sect-uuid-3", "order_index": 2, "level": 2 }
  ]
}

Request Parameters

Parameter	Type	Required	Description
`sections`	array	Yes	List of `{section_id, order_index, level}` objects defining the new order

Request Example

curl -X PUT "https://api.artosai.com/api/v1/templates/tmpl-uuid-1/sections/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sections": [
      { "section_id": "sect-uuid-2", "order_index": 0, "level": 1 },
      { "section_id": "sect-uuid-1", "order_index": 1, "level": 1 },
      { "section_id": "sect-uuid-3", "order_index": 2, "level": 2 }
    ]
  }'

Response

{
  "template_id": "tmpl-uuid-1",
  "sections": [
    {
      "section_id": "sect-uuid-2",
      "section_name": "1. Study Design",
      "order_index": 0,
      "level": 1
    },
    {
      "section_id": "sect-uuid-1",
      "section_name": "2. Executive Summary",
      "order_index": 1,
      "level": 1
    },
    {
      "section_id": "sect-uuid-3",
      "section_name": "2.1 Safety Overview",
      "order_index": 2,
      "level": 2
    }
  ],
  "message": "Sections reordered and renumbered successfully"
}

Status Codes

200 OK: Sections reordered successfully
400 Bad Request: Authentication errors
403 Forbidden: Unauthorized access
404 Not Found: Template not found
500 Internal Server Error: Database operation failure

Update Rule Styles

Update the style names, fill color, and/or text color for a specific rule within a template section.

PUT /api/v1/templates/{template_id}/rules/{rule_id}/styles

Path Parameters

Parameter	Type	Required	Description
`template_id`	string	Yes	UUID of the template (used for authorization)
`rule_id`	string	Yes	UUID of the rule to update

Request Body

{
  "style_names": ["Heading 2", "Normal"],
  "fill": "#FFFF00",
  "color": "#FF0000"
}

Request Parameters

Parameter	Type	Required	Description
`style_names`	array	No	List of Word style names to apply (e.g., `["Heading 2", "Normal"]`)
`fill`	string	No	Background fill color as hex (e.g., `"#FFFF00"`), or `null`/`""` to remove
`color`	string	No	Text/font color as hex (e.g., `"#FF0000"`), or `null`/`""` to remove

Request Example

curl -X PUT "https://api.artosai.com/api/v1/templates/tmpl-uuid-1/rules/rule-uuid-1/styles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "style_names": ["Heading 2"],
    "fill": "#FFF2CC",
    "color": null
  }'

Response

{
  "rule_id": "rule-uuid-1",
  "styles": {
    "style_names": ["Heading 2"],
    "fill": "#FFF2CC",
    "color": null
  },
  "updated": true
}

Status Codes

200 OK: Rule styles updated successfully
400 Bad Request: Authentication errors
403 Forbidden: Unauthorized access
404 Not Found: Template or rule not found
500 Internal Server Error: Database operation failure

Delete Template Section

Delete a section from an template. Associated rules are automatically deleted via CASCADE.

DELETE /api/v1/templates/{template_id}/sections/{section_id}

Path Parameters

Parameter	Type	Required	Description
`template_id`	string	Yes	UUID of the template
`section_id`	string	Yes	UUID of the section to delete

Query Parameters

Parameter	Type	Required	Default	Description
`cascade_children`	boolean	No	`true`	If `true`, also delete child sections at deeper nesting levels

Request Example

# Delete section and its children
curl -X DELETE "https://api.artosai.com/api/v1/templates/tmpl-uuid-1/sections/sect-uuid-1" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Delete only this section (leave children)
curl -X DELETE "https://api.artosai.com/api/v1/templates/tmpl-uuid-1/sections/sect-uuid-1?cascade_children=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "message": "Section deleted successfully",
  "deleted_section_id": "sect-uuid-1",
  "deleted_count": 1
}

Response Fields

Field	Type	Description
`message`	string	Success message
`deleted_section_id`	string	UUID of the deleted section
`deleted_count`	integer	Total number of sections deleted (includes children if cascaded)

Status Codes

200 OK: Section deleted successfully
400 Bad Request: Invalid parameters
403 Forbidden: Not authorized
404 Not Found: Template or section not found

Getting Started

API Reference

Core Concepts

Cookbooks

SDK Reference

Integrations

Deployment

Documentation Index

​Templates API

​List Templates

​Request Example

​Response

​Status Codes

​Get Single Template

​Path Parameters

​Request Example

​Response

​Status Codes

​Create Template

​Request Body

​Request Parameters

​Section Parameters

​Request Example

​Python Example

​Response (201 Created)

​Response Fields

​Status Codes

​Add Section to Template

​Path Parameters

​Request Body

​Request Parameters

​Request Example

​Response

​Status Codes

​Rename Template Section

​Path Parameters

​Request Body

​Request Parameters

​Request Example

​Response

​Status Codes

​Reorder Template Sections

​Path Parameters

​Request Body

​Request Parameters

​Request Example

​Response

​Status Codes

​Update Rule Styles

​Path Parameters

​Request Body

​Request Parameters

​Request Example

​Response

​Status Codes

​Delete Template Section

​Path Parameters

​Query Parameters

​Request Example

​Response

​Response Fields

​Status Codes

Templates API

List Templates

Request Example

Response

Status Codes

Get Single Template

Path Parameters

Request Example

Response

Status Codes

Create Template

Request Body

Request Parameters

Section Parameters

Request Example

Python Example

Response (201 Created)

Response Fields

Status Codes

Add Section to Template

Path Parameters

Request Body

Request Parameters

Request Example

Response

Status Codes

Rename Template Section

Path Parameters

Request Body

Request Parameters

Request Example

Response

Status Codes

Reorder Template Sections

Path Parameters

Request Body

Request Parameters

Request Example

Response

Status Codes

Update Rule Styles

Path Parameters

Request Body

Request Parameters

Request Example

Response

Status Codes

Delete Template Section

Path Parameters

Query Parameters

Request Example

Response

Response Fields

Status Codes