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

# Save Document Studio Report

> Save or create a document studio report with rich content and automatic version control

Save a document studio report with rich formatting, dynamic content, and automatic version management. This endpoint creates a new version of the report each time it's called, maintaining a complete version history.

## Path Parameters

<ParamField path="projectId" type="string" required>
  The unique identifier of the project associated with the report
</ParamField>

## Request Body

<ParamField body="reportName" type="string" required>
  The name of the report. This serves as a unique identifier within the project scope.
</ParamField>

<ParamField body="content" type="object" required>
  The complete report content structure including blocks, formatting, and data

  <Expandable title="content structure">
    <ParamField body="blocks" type="array" required>
      Array of content blocks that make up the report

      <Expandable title="block types">
        <ParamField body="type" type="string" required>
          Type of content block: "title", "narrative", "data", "table", "section", "list"
        </ParamField>

        <ParamField body="content" type="string">
          The actual content of the block (for text-based blocks)
        </ParamField>

        <ParamField body="properties" type="object">
          Block-specific properties and configuration

          <Expandable title="common properties">
            <ParamField body="sectionId" type="string">
              Unique identifier for the section (used for narrative blocks)
            </ParamField>

            <ParamField body="title" type="string">
              Display title for the block
            </ParamField>

            <ParamField body="required" type="boolean">
              Whether this block requires content (for templates)
            </ParamField>

            <ParamField body="fontSize" type="string">
              Font size (e.g., "16px", "1.2em")
            </ParamField>

            <ParamField body="textAlign" type="string">
              Text alignment: "left", "center", "right", "justify"
            </ParamField>

            <ParamField body="color" type="string">
              Text color (hex code or CSS color name)
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="children" type="array">
          Child blocks (for section-type blocks)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="metadata" type="object">
      Report metadata and configuration

      <Expandable title="metadata">
        <ParamField body="templateId" type="string">
          ID of the template this report is based on
        </ParamField>

        <ParamField body="reportType" type="string">
          Type of report: "GENERAL", "INITIAL", "INTERIM", "FINAL"
        </ParamField>

        <ParamField body="author" type="string">
          Author of the report
        </ParamField>

        <ParamField body="lastModified" type="string">
          ISO timestamp of last modification
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Example Request

```json theme={null}
{
  "reportName": "Q2 Progress Report",
  "content": {
    "blocks": [
      {
        "type": "title",
        "content": "Quarterly Progress Report",
        "properties": {
          "fontSize": "24px",
          "textAlign": "center",
          "color": "#2c3e50"
        }
      },
      {
        "type": "section",
        "properties": {
          "title": "Executive Summary"
        },
        "children": [
          {
            "type": "narrative",
            "properties": {
              "sectionId": "executive-summary",
              "title": "Project Overview",
              "required": true
            },
            "content": "<p>The project has made significant progress during Q2 2024, with major milestones achieved in foundation work and structural development.</p>"
          }
        ]
      },
      {
        "type": "data",
        "properties": {
          "title": "Financial Summary",
          "dataSource": "project.financials",
          "format": "currency"
        }
      },
      {
        "type": "table",
        "properties": {
          "title": "Risk Assessment Summary",
          "dataSource": "project.riskAssessments",
          "columns": [
            {"key": "category", "title": "Risk Category"},
            {"key": "status", "title": "Current Status"},
            {"key": "notes", "title": "Notes"}
          ]
        }
      },
      {
        "type": "list",
        "properties": {
          "sectionId": "key-achievements",
          "title": "Key Achievements",
          "listType": "bullet"
        },
        "content": "Foundation work completed ahead of schedule\nSteel frame installation commenced\nAll safety milestones met"
      }
    ],
    "metadata": {
      "templateId": "template-001",
      "reportType": "INTERIM",
      "author": "Project Surveyor",
      "lastModified": "2024-06-20T14:30:00.000Z"
    }
  }
}
```

## Response

Returns the saved report information including the new version number:

<ResponseField name="reportId" type="string">
  Unique identifier of the report
</ResponseField>

<ResponseField name="version" type="number">
  Version number of the newly created version
</ResponseField>

## Example Response

```json theme={null}
{
  "reportId": "report-12345",
  "version": 3
}
```

## Block Types Reference

### Title Block

Used for report titles and major headings:

```json theme={null}
{
  "type": "title",
  "content": "Report Title",
  "properties": {
    "fontSize": "24px",
    "textAlign": "center",
    "color": "#333333"
  }
}
```

### Narrative Block

For rich text content with editing capabilities:

```json theme={null}
{
  "type": "narrative",
  "properties": {
    "sectionId": "unique-section-id",
    "title": "Section Title",
    "required": true
  },
  "content": "<p>Rich HTML content with <strong>formatting</strong></p>"
}
```

### Data Block

For dynamic project data integration:

```json theme={null}
{
  "type": "data",
  "properties": {
    "title": "Project Costs",
    "dataSource": "project.costs.total",
    "format": "currency",
    "calculation": "sum"
  }
}
```

### Table Block

For structured data presentation:

```json theme={null}
{
  "type": "table",
  "properties": {
    "title": "Cost Breakdown",
    "dataSource": "project.facilities",
    "columns": [
      {"key": "name", "title": "Facility"},
      {"key": "budget", "title": "Budget", "format": "currency"},
      {"key": "actual", "title": "Actual", "format": "currency"}
    ]
  }
}
```

### Section Block

For organizing content into logical sections:

```json theme={null}
{
  "type": "section",
  "properties": {
    "title": "Financial Analysis"
  },
  "children": [
    // Child blocks go here
  ]
}
```

### List Block

For bullet points and numbered lists:

```json theme={null}
{
  "type": "list",
  "properties": {
    "sectionId": "achievements",
    "title": "Key Achievements",
    "listType": "bullet"
  },
  "content": "Item 1\nItem 2\nItem 3"
}
```

## Version Management

Document Studio automatically manages versions:

* **Auto-Increment**: Each save creates a new version with incremented number
* **Version History**: Complete history is maintained for all versions
* **No Overwrites**: Previous versions are never lost or modified
* **Timestamp Tracking**: Each version includes creation timestamp
* **User Attribution**: Version changes are tracked by user

## Content Validation

The system validates report content:

* **Block Structure**: Ensures all blocks have required properties
* **Data References**: Validates that data sources exist and are accessible
* **HTML Safety**: Sanitizes HTML content in narrative blocks
* **Required Fields**: Checks that required narrative sections have content
* **JSON Schema**: Validates overall content structure against schema

## Integration with Templates

Reports can be based on templates:

* **Template Inheritance**: Reports inherit structure from templates
* **Custom Modifications**: Template-based reports can be customized
* **Required Sections**: Template requirements are enforced
* **Dynamic Content**: Template placeholders are populated with project data

## Error Responses

<ResponseField name="400" type="error">
  **Bad Request** - Invalid content structure or missing required fields

  ```json theme={null}
  {
    "statusCode": 400,
    "message": "Invalid block structure",
    "error": "Bad Request"
  }
  ```
</ResponseField>

<ResponseField name="404" type="error">
  **Not Found** - Project not found or user lacks access

  ```json theme={null}
  {
    "statusCode": 404,
    "message": "Project not found",
    "error": "Not Found"
  }
  ```
</ResponseField>

<ResponseField name="413" type="error">
  **Payload Too Large** - Report content exceeds size limits

  ```json theme={null}
  {
    "statusCode": 413,
    "message": "Report content too large",
    "error": "Payload Too Large"
  }
  ```
</ResponseField>

## Best Practices

* **Unique Section IDs**: Use consistent, unique section IDs for narrative blocks
* **Structured Content**: Organize content logically using section blocks
* **Data Integration**: Leverage data blocks for dynamic project information
* **Regular Saves**: Save frequently to maintain version history
* **Content Validation**: Validate required sections before final save
* **Template Consistency**: Follow template structures when applicable

## Related Endpoints

* [Get Report](/api-reference/document-studio/get-report) - Retrieve a specific report version
* [List Report Versions](/api-reference/document-studio/list-versions) - View version history
* [Export Report](/api-reference/document-studio/export-report) - Export as PDF