> ## 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.

# npm SDK API Reference

> Complete API reference for all functions in the Artos npm SDK (@artosai/sdk).

# npm SDK API Reference

## `getTemplateUrl(options)`

Retrieves the template associated with a document and returns a presigned URL that can be used directly to fetch the file. The presigned URL expires after 1 hour.

**Parameters:**

| Parameter     | Type        | Required | Description                                |
| ------------- | ----------- | -------- | ------------------------------------------ |
| `documentId`  | `string`    | Yes      | The unique identifier of the document      |
| `accessToken` | `string`    | Yes      | Your organization access token             |
| `baseUrl`     | `string`    | Yes      | The Artos API base URL                     |
| `apiClient`   | `ApiClient` | No       | Pre-configured API client (advanced usage) |

**Returns:** `Promise<GetTemplateUrlResponse>`

```typescript theme={null}
interface GetTemplateUrlResponse {
    templateUrl: string | null    // Presigned URL for the template file (expires in 1 hour)
    templateId: string | null     // Unique template identifier
    documentName: string | null   // Name of the document
    _raw: object                  // Full API response (for debugging)
}
```

***

## `getDocumentSources(options)`

Lists all sources associated with a given section within a document. Used to populate the Sources panel when a user selects or highlights a section of the draft.

**Parameters:**

| Parameter     | Type        | Required | Description                                |
| ------------- | ----------- | -------- | ------------------------------------------ |
| `documentId`  | `string`    | Yes      | The unique identifier of the document      |
| `sectionId`   | `string`    | Yes      | The section ID to retrieve sources for     |
| `accessToken` | `string`    | Yes      | Your organization access token             |
| `baseUrl`     | `string`    | Yes      | The Artos API base URL                     |
| `apiClient`   | `ApiClient` | No       | Pre-configured API client (advanced usage) |

**Returns:** `Promise<GetDocumentSourcesResponse>`

```typescript theme={null}
interface GetDocumentSourcesResponse {
    sources: Array<{
        documentSourceId: string | null    // Unique identifier of the source record
        documentSourceName: string | null  // Human-readable display name of the source
        referencedText: string | null      // Exact excerpt used to generate the section
        _raw: object                       // Full API response for this source
    }>
}
```

***

## `getDocumentSourceUrl(options)`

Fetches the presigned URL for a given source reference, enabling preview of the original source material from within the Sources panel.

**Parameters:**

| Parameter          | Type        | Required | Description                                  |
| ------------------ | ----------- | -------- | -------------------------------------------- |
| `documentSourceId` | `string`    | Yes      | Source ID obtained from `getDocumentSources` |
| `accessToken`      | `string`    | Yes      | Your organization access token               |
| `baseUrl`          | `string`    | Yes      | The Artos API base URL                       |
| `apiClient`        | `ApiClient` | No       | Pre-configured API client (advanced usage)   |

**Returns:** `Promise<GetDocumentSourceUrlResponse>`

```typescript theme={null}
interface GetDocumentSourceUrlResponse {
    documentSourceUrl: string | null    // Presigned URL to the original source document
    _raw: object                        // Full API response (for debugging)
}
```

***

## `getSectionFromText(options)`

Given a user-defined text selection within the draft editor, identifies the enclosing section and returns its metadata. Use the returned `sectionId` with `getDocumentSources` to retrieve sources for that section.

**Parameters:**

| Parameter         | Type        | Required | Description                                 |
| ----------------- | ----------- | -------- | ------------------------------------------- |
| `documentId`      | `string`    | Yes      | The document ID                             |
| `highlightedText` | `string`    | Yes      | The raw text string of the user's selection |
| `accessToken`     | `string`    | Yes      | Your organization access token              |
| `baseUrl`         | `string`    | Yes      | The Artos API base URL                      |
| `apiClient`       | `ApiClient` | No       | Pre-configured API client (advanced usage)  |

**Returns:** `Promise<GetSectionFromTextResponse>`

```typescript theme={null}
interface GetSectionFromTextResponse {
    sectionId: string | null    // ID of the section containing the highlighted text
    _raw: object                // Full API response (for debugging)
}
```

***

## `getDocumentSections(options)`

Retrieves all sections for a given document, returning each section's ID, title, and display order. Useful for building navigation, table of contents, or populating section selectors.

**Parameters:**

| Parameter     | Type        | Required | Description                                |
| ------------- | ----------- | -------- | ------------------------------------------ |
| `documentId`  | `string`    | Yes      | The unique identifier of the document      |
| `accessToken` | `string`    | Yes      | Your organization access token             |
| `baseUrl`     | `string`    | Yes      | The Artos API base URL                     |
| `apiClient`   | `ApiClient` | No       | Pre-configured API client (advanced usage) |

**Returns:** `Promise<GetDocumentSectionsResponse>`

```typescript theme={null}
interface GetDocumentSectionsResponse {
    sections: Array<{
        sectionId: string | null       // Unique identifier of the section
        sectionTitle: string | null    // Human-readable title of the section
        sectionOrder: number | null    // Display order within the document
        _raw: object                   // Full API response for this section
    }>
}
```

***

## `generateProxyUrl(options)`

Fetches a file by streaming it through the backend's proxy endpoint. Takes a presigned S3 URL and streams the file content back, returning it as a Blob. Useful for displaying source documents in the browser without exposing S3 URLs directly.

**Parameters:**

| Parameter      | Type        | Required | Description                                    |
| -------------- | ----------- | -------- | ---------------------------------------------- |
| `presignedUrl` | `string`    | Yes      | A presigned S3 URL to stream through the proxy |
| `baseUrl`      | `string`    | Yes      | The Artos API base URL                         |
| `apiClient`    | `ApiClient` | No       | Pre-configured API client (advanced usage)     |

**Returns:** `Promise<GenerateProxyUrlResponse>`

```typescript theme={null}
interface GenerateProxyUrlResponse {
    blob: Blob          // The file content as a Blob
    contentType: string // The content type (e.g. 'application/pdf')
    proxyUrl: string    // The proxy URL used to fetch the file
}
```

***

## `getDocumentPresignedUrl(options)`

Retrieves a presigned URL for downloading a generated document file. The backend locates the document in S3 (checking internal and output paths) and returns a time-limited presigned URL that can be used to fetch or display the file directly.

**Parameters:**

| Parameter     | Type        | Required | Description                                |
| ------------- | ----------- | -------- | ------------------------------------------ |
| `documentId`  | `string`    | Yes      | The unique identifier of the document      |
| `accessToken` | `string`    | Yes      | Your organization access token             |
| `baseUrl`     | `string`    | Yes      | The Artos API base URL                     |
| `apiClient`   | `ApiClient` | No       | Pre-configured API client (advanced usage) |

**Returns:** `Promise<GetDocumentPresignedUrlResponse>`

```typescript theme={null}
interface GetDocumentPresignedUrlResponse {
    documentUrl: string | null    // Presigned URL for downloading the document file
    _raw: object                  // Full API response (for debugging)
}
```

***

## `getSectionRules(options)`

Retrieves all rules for a given document MRT section, including resolved source chunks, tables, presigned URLs, template URLs, breadcrumbs, and rule metadata. This is the primary function for building rule-level detail panels, audit trails, and source traceability views in your UI.

**Parameters:**

| Parameter     | Type        | Required | Description                                     |
| ------------- | ----------- | -------- | ----------------------------------------------- |
| `sectionId`   | `string`    | Yes      | The MRT section ID (from `getDocumentSections`) |
| `accessToken` | `string`    | Yes      | Your organization access token                  |
| `baseUrl`     | `string`    | Yes      | The Artos API base URL                          |
| `apiClient`   | `ApiClient` | No       | Pre-configured API client (advanced usage)      |

**Returns:** `Promise<GetSectionRulesResponse>`

```typescript theme={null}
interface GetSectionRulesResponse {
    sectionId: string                // The MRT section ID
    rules: SectionRule[]             // Array of rules with resolved source data
}

interface SectionRule {
    ruleId: string | null                   // Unique rule identifier
    ruleType: string | null                 // Rule type (see Rule Types below)
    ruleMode: string | null                 // "dynamic" or "static"
    description: string | null              // Human-readable rule description
    explanation: string | null              // How the rule was applied
    generatedContent: string | null         // The content produced by this rule
    confidenceScore: number | null          // 0-1 confidence score
    orderIndex: number | null               // Execution order within the section (0-based)
    ruleTemplateText: string | null         // Original template text the rule refers to
    templateUrl: string | null              // Presigned URL for the template file (template rules only)
    breadcrumbs: RuleBreadcrumbs | null     // Generation/processing trace (see Breadcrumbs Reference)
    ruleMetadata: RuleMetadata | null       // Structured rule metadata (see Rule Metadata Reference)
    sourceChunk: RuleSourceChunk | null     // Single source chunk (copy_paste/summarize rules)
    sourceChunks: RuleSourceChunk[]         // Multiple source chunks (template rules)
    table: RuleTable | null                 // Associated table data (table rules)
    _raw: Record<string, any>              // Full API response for this rule
}
```

### Rule Types

| Rule Type                | Category    | Description                               | Has `templateUrl` | Source Fields           |
| ------------------------ | ----------- | ----------------------------------------- | ----------------- | ----------------------- |
| `template_text`          | Template    | Text generated from template instructions | Yes               | `sourceChunks`          |
| `template_table`         | Template    | Table generated from template structure   | Yes               | `sourceChunks`, `table` |
| `copy_paste`             | Extraction  | Direct excerpt from a source document     | No                | `sourceChunk`           |
| `summarize_content`      | Extraction  | Summarized content from a source          | No                | `sourceChunk`           |
| `copy_paste_placeholder` | Placeholder | Placeholder for future copy/paste         | No                | -                       |
| `template_text_rule`     | Template    | Alias for `template_text`                 | Yes               | `sourceChunks`          |
| `template_table_rule`    | Template    | Alias for `template_table`                | Yes               | `sourceChunks`, `table` |

### `templateUrl`

A presigned S3 URL pointing to the original template file used during document generation. Only populated for template-related rules (`template_text`, `template_table`, and their `_rule` variants). The URL expires after **1 hour**.

Use this to let users view or download the original template alongside the generated content, enabling side-by-side comparison of what the template instructed vs. what was produced.

***

## TypeScript Support

The SDK includes full TypeScript definitions. Import types as needed:

```typescript theme={null}
import {
    getTemplateUrl,
    getDocumentSources,
    getDocumentSourceUrl,
    getSectionFromText,
    getDocumentSections,
    getDocumentPresignedUrl,
    generateProxyUrl,
    getSectionRules,
    createApiClient,
    ArtosAPIError
} from '@artosai/sdk'

import type {
    ApiClient,
    ApiClientConfig,
    ApiCallOptions,
    GetTemplateUrlOptions,
    GetTemplateUrlResponse,
    GetDocumentSourcesOptions,
    GetDocumentSourcesResponse,
    GetDocumentSourceUrlOptions,
    GetDocumentSourceUrlResponse,
    GetSectionFromTextOptions,
    GetSectionFromTextResponse,
    GetDocumentSectionsOptions,
    GetDocumentSectionsResponse,
    GetDocumentPresignedUrlOptions,
    GetDocumentPresignedUrlResponse,
    GenerateProxyUrlOptions,
    GenerateProxyUrlResponse,
    GetSectionRulesOptions,
    GetSectionRulesResponse,
    SectionRule,
    RuleSourceChunk,
    RuleTable,
    DocumentSource,
    DocumentSection
} from '@artosai/sdk'
```

### Fully Typed Example

```typescript theme={null}
async function typedExample(): Promise<GetTemplateUrlResponse> {
    const options: GetTemplateUrlOptions = {
        documentId: 'doc-123',
        accessToken: process.env.ARTOS_ACCESS_TOKEN!,
        baseUrl: 'https://api.artosai.com'
    }

    const result: GetTemplateUrlResponse = await getTemplateUrl(options)
    return result
}
```