npm SDK API Reference

All methods accept an Okta access-token JWT through accessToken. File-related methods use opaque resource IDs returned by Artos APIs; callers should not construct them from URLs or arbitrary storage keys. Use openFile as the unified entry point for Apryse previews/downloads and OnlyOffice.

Backward compatibility

The SDK preserves the pre-resource API names and response fields while using the new backend session flow internally:

Legacy API	Compatibility behavior	Preferred API
`getTemplateUrl`	Returns `templateUrl` backed by `document-file-session`	`getTemplateResource` + `openFile`
`getDocumentSourceUrl`	Returns the `/source-file` endpoint in the legacy field	`getDocumentSourceResource` + `openFile`
`getDocumentPresignedUrl`	Returns `documentUrl` backed by `document-file-session`	`openFile`
`generateProxyUrl`	Accepts a resource ID or legacy URL	`openFile`

The legacy methods and TypeScript interfaces remain exported and are deprecated. URL-valued fields are endpoint-only compatibility values, not S3 presigned URLs or standalone download links. The package default export remains getTemplateUrl for existing default imports.

`getTemplateResource(options)`

Retrieves the template metadata associated with a document.

Parameter	Type	Required	Description
`documentId`	`string`	Yes	Document ID
`accessToken`	`string`	Yes	Okta access-token JWT
`baseUrl`	`string`	No	Artos API base URL
`apiClient`	`ApiClient`	No	Reusable API client

interface GetTemplateResourceResponse {
    templateResourceId: string | null
    templateId: string | null
    templateFileName: string | null
    documentName: string | null
    _raw: object
}

templateResourceId is an opaque value. Pass it to openFile with viewer: 'apryse' for file bytes or viewer: 'onlyoffice' for the editor.

Getting a `resourceId`

Use the value returned by the API that produced or identified the file:

getTemplateResource returns templateResourceId.
getDocumentSourceResource returns resourceId for a source file. Obtain its documentSourceId from getDocumentSources.
getSectionRules returns resource IDs on templateResourceId, sourceChunk.resourceId, sourceChunks[].resourceId, and table.resourceId.
File-list and upload responses return resource_id for directly managed source files.

Pass the returned value unchanged:

const file = await openFile({
    resourceId: source.resourceId,
    accessToken,
    baseUrl
})

For sourcefile-... values, openFile with viewer: 'apryse' uses authenticated POST /source-file. Other resource IDs use the document-file-session flow. getTemplateUrl is retained for compatibility. It returns the resource metadata above plus the legacy templateUrl endpoint-only field. New code should use getTemplateResource and openFile explicitly.

`getTemplateUrl(options)` (deprecated)

Keeps the original method name and returns an endpoint-only templateUrl field for compatibility. It is not a standalone download URL; use the returned templateResourceId with openFile.

interface GetTemplateUrlResponse extends GetTemplateResourceResponse {
    templateUrl: string | null
}

`getDocumentSources(options)`

Lists the source references associated with a document section.

interface GetDocumentSourcesResponse {
    sources: Array<{
        documentSourceId: string | null
        documentSourceName: string | null
        referencedText: string | null
        _raw: object
    }>
}

`getDocumentSourceResource(options)`

Resolves a source reference to an opaque Artos resource ID.

Parameter	Type	Required	Description
`documentSourceId`	`string`	Yes	Source ID from `getDocumentSources`
`accessToken`	`string`	Yes	Okta access-token JWT

interface GetDocumentSourceResourceResponse {
    resourceId: string | null
    documentName: string | null
    _raw: object
}

getDocumentSourceUrl is retained for compatibility. It returns the resource metadata above plus the legacy documentSourceUrl field, which contains only the /source-file POST endpoint. New code should use getDocumentSourceResource and openFile explicitly.

`getDocumentSourceUrl(options)` (deprecated)

Keeps the original method name and returns the /source-file POST endpoint in documentSourceUrl; callers should use openFile with the returned resource ID.

interface GetDocumentSourceUrlResponse extends GetDocumentSourceResourceResponse {
    documentSourceUrl: string | null
}

`createDocumentFileSession(options)`

Authorizes a resource and creates a short-lived, revocable document-viewer session.

Parameter	Type	Required	Description
`resourceId`	`string`	Yes	Opaque file, document, or template resource ID
`accessToken`	`string`	Yes	Okta access-token JWT
`baseUrl`	`string`	No	Artos API base URL
`apiClient`	`ApiClient`	No	Reusable API client

interface CreateDocumentFileSessionResponse {
    sessionToken: string | null
    openDocumentUrl: string | null
    resourceId: string
    _raw: object
}

openDocumentUrl is a compatibility endpoint only; it is not a standalone download URL. Prefer openFile for normal integrations. If using openDocument directly, keep the returned session value in memory and request a new session after it expires.

`openDocument(options)`

Streams document bytes using a session token returned by createDocumentFileSession.

interface OpenDocumentOptions {
    sessionToken: string
    sessionTransport?: 'header' | 'query'
    baseUrl?: string
    apiClient?: ApiClient
}

interface OpenDocumentResponse {
    blob: Blob
    contentType: string
    fileName: string | null
}

openDocument is a lower-level method intended for advanced integrations. Most applications should not call it directly: use openFile instead. It accepts a session token created with createDocumentFileSession and streams the file from GET /open-document when an application needs to manage that session itself.

`openSourceFile(options)`

Streams a source file through POST /source-file. The user’s organization Bearer token is sent with the request and authorization is performed for every read. This is the SDK method for source-file previews and downloads; do not create a document session for this use case.

interface OpenSourceFileOptions {
    resourceId: string
    accessToken: string | { accessToken: string }
    baseUrl?: string
    apiClient?: ApiClient
}

interface OpenSourceFileResponse {
    blob: Blob
    contentType: string
    fileName: string | null
    resourceId: string
    sourceFileUrl: string // POST endpoint, not a standalone download URL
}

`openFile(options)`

Recommended unified entry point for Apryse file access and OnlyOffice. Use viewer: 'apryse' for authenticated file bytes or viewer: 'onlyoffice' for the editor configuration and token.

interface OpenFileOptions {
    resourceId: string
    accessToken: string | { accessToken: string }
    viewer?: 'apryse' | 'onlyoffice' // defaults to 'apryse'
    mode?: 'edit' | 'readonly'
    customization?: object | null
    displayType?: 'desktop' | 'mobile' | 'embedded' | null
    sessionTransport?: 'header' | 'query'
    baseUrl?: string
    apiClient?: ApiClient
}

interface OpenFileApryseResponse {
    viewer: 'apryse'
    blob: Blob
    contentType: string
    fileName: string | null
    resourceId: string
    sourceFileUrl?: string
}

interface OpenFileOnlyOfficeResponse {
    viewer: 'onlyoffice'
    config: object | null
    token: string | null
    resourceId: string
    _raw: object
}

type OpenFileResponse =
    | OpenFileApryseResponse
    | OpenFileOnlyOfficeResponse

Available in SDK 1.0.13 and later, sessionTransport defaults to 'header'. Set it to 'query' only for an Artos API deployment that requires compatibility transport for Apryse document or template loads. This setting does not apply to source files. The return type depends entirely on viewer:

`viewer`	Return value	Use it for
`'apryse'`	`OpenFileApryseResponse` containing `blob`, `contentType`, `fileName`, and `resourceId`	PDF/document previews, downloads, or passing bytes to Apryse
`'onlyoffice'`	`OpenFileOnlyOfficeResponse` containing `config`, `token`, and `resourceId`	Mounting the OnlyOffice editor

An 'onlyoffice' response never contains a blob. An 'apryse' response never contains config or an OnlyOffice token. Inspect response.viewer before using the response:

const response = await openFile({
    resourceId,
    accessToken,
    baseUrl,
    viewer: 'onlyoffice',
    mode: 'readonly'
})

if (response.viewer === 'onlyoffice') {
    // `DocsAPI` is provided by the OnlyOffice editor API script.
    new DocsAPI.DocEditor('onlyoffice-editor', {
        ...response.config,
        token: response.token
    })
}

Your page must include an OnlyOffice editor container and load the OnlyOffice api.js script before this code runs. DocsAPI.DocEditor is not provided by the Artos SDK; the SDK only returns config and token. For an Apryse preview, use the Blob branch instead:

const response = await openFile({
    resourceId,
    accessToken,
    baseUrl,
    viewer: 'apryse'
})

if (response.viewer === 'apryse') {
    const previewUrl = URL.createObjectURL(response.blob)
    // Give previewUrl to Apryse, then revoke it when the preview is replaced.
}

`generateOnlyOfficeConfig(options)` (lower-level)

Creates a server-generated OnlyOffice configuration for a resource. Most applications should call openFile({ viewer: 'onlyoffice' }), which performs this step automatically. Use this lower-level method only when you need the OnlyOffice configuration without the unified dispatcher.

OnlyOffice opening flow

The application obtains a resourceId from an Artos response, such as templateResourceId or a source/rule resource ID.
The application calls openFile({ viewer: 'onlyoffice' }) with the user’s access-token JWT. The SDK calls generateOnlyOfficeConfig internally.
The backend authenticates the user, authorizes the resource, creates a short-lived OnlyOffice document session, and builds the editor config.
The application passes the returned config and token to the OnlyOffice editor component.
OnlyOffice fetches the document through the backend’s configured document route. The backend validates the session and OnlyOffice token before streaming the file from storage.
For editable documents, OnlyOffice sends save callbacks to the backend.

The application does not download the document with the Apryse branch of openFile before opening OnlyOffice. OnlyOffice retrieves the document using the server-generated configuration returned by the OnlyOffice branch.

`mode` values and editing behavior

edit requests an editable editor. The backend still enforces whether the resource is actually editable.
readonly creates a non-editable preview. The backend disables edit permissions, removes the save callback, and disables forced saves.
Source files, templates, generated outputs, and duplicate outputs are inherently read-only even if mode: 'edit' is requested.

Save synchronization

For an editable document, the backend includes a callbackUrl in the config. OnlyOffice calls that endpoint when the document is ready to be saved. The backend verifies the document session and OnlyOffice JWT, checks that the callback targets the authorized document, downloads the saved file from the OnlyOffice-provided URL, uploads it to storage, updates the document’s updated_at value, and returns { "error": 0 }. To keep saves synchronized:

Use mode: 'edit' only for resources the user is allowed to edit.
Keep the returned config and token together for one editor instance.
Do not modify document.url, callbackUrl, document.key, or permissions in the client.
Treat an OnlyOffice error event or a failed save callback as a failed save; do not report the document as synchronized until the callback succeeds.
Generate a fresh configuration when reopening a document or after the session has expired. The refreshed document.key incorporates the current document version.

Parameter	Type	Required	Description
`resourceId`	`string`	Yes	Opaque file, document, or template resource ID
`accessToken`	`string`	Yes	Okta access-token JWT
`mode`	`'edit' \| 'readonly'`	No	Viewer mode; defaults to `'edit'`
`customization`	`object`	No	OnlyOffice customization options
`displayType`	`'desktop' \| 'mobile' \| 'embedded'`	No	Viewer layout

interface GenerateOnlyOfficeConfigResponse {
    config: object | null
    token: string | null
    _raw: object
}

Pass config and token to the OnlyOffice editor component. The same values are returned by openFile({ viewer: 'onlyoffice' }); the lower-level method is available only when you specifically want to call the config endpoint yourself.

`getDocumentPresignedUrl(options)` (deprecated)

Keeps the original method name while using get-one-document and document-file-session internally. The legacy documentUrl field is now a token-free document endpoint, not an S3 presigned URL or standalone download link.

interface GetDocumentPresignedUrlResponse {
    documentUrl: string | null
    resourceId: string
    _raw: object
}

`generateProxyUrl(options)` (deprecated)

The original export remains available. Prefer openFile for new code. The compatibility method accepts a resource ID plus access token, or an existing legacy URL.

interface GenerateProxyUrlOptions {
    presignedUrl?: string
    resourceId?: string
    accessToken?: string
    baseUrl?: string
    apiClient?: ApiClient
}

interface GenerateProxyUrlResponse {
    blob: Blob
    contentType: string
    proxyUrl: string
}

When resourceId starts with sourcefile-, the SDK uses the authenticated /source-file route and checks the user’s access token on every request. Other resource IDs use the document-session flow. An existing legacy URL is fetched directly for compatibility. Prefer openFile for all new file access.

`getSectionRules(options)`

Retrieves the rules for an MRT section, including resolved source chunks and tables, resource IDs for referenced files, rule metadata, and breadcrumb traces from the generation, postprocessing, and style-guide stages.

interface GetSectionRulesResponse {
    sectionId: string
    rules: Array<{
        ruleId: string | null
        ruleType: string | null
        ruleMode: string | null
        description: string | null
        explanation: string | null
        generatedContent: string | null
        confidenceScore: number | null
        orderIndex: number | null
        ruleTemplateText: string | null
        templateResourceId: string | null
        templateUrl: string | null // Deprecated compatibility field
        breadcrumbs: Record<string, any> | null
        ruleMetadata: Record<string, any> | null
        sourceChunk: RuleSourceChunk | null
        sourceChunks: RuleSourceChunk[]
        table: RuleTable | null
        _raw: object
    }>
}

interface RuleSourceChunk {
    chunkId: string
    content: string | null
    sectionName: string | null
    pageNumber: number | null
    resourceId: string | null
    fileName: string | null
    presignedUrl: string | null // Deprecated compatibility field
    _raw: object
}

interface RuleTable {
    tableId: string
    tableTitle: string | null
    tableMarkdown: string | null
    pageNumber: number | null
    resourceId: string | null
    fileName: string | null
    presignedUrl: string | null // Deprecated compatibility field
    _raw: object
}

fileName is the basename derived from the source object’s file path when that metadata is available. breadcrumbs is the rule’s structured execution trace and may be null when no trace was recorded. The legacy templateUrl and presignedUrl fields are compatibility values. For new file previews, pass a returned resourceId or templateResourceId to openFile. getSectionFromText and getDocumentSections are also available for resolving a selected section and listing a document’s sections.

TypeScript imports

import {
    createApiClient,
    createDocumentFileSession,
    generateOnlyOfficeConfig,
    generateProxyUrl,
    getDocumentPresignedUrl,
    getDocumentSourceResource,
    getDocumentSources,
    getDocumentSections,
    getSectionFromText,
    getSectionRules,
    getTemplateResource,
    getTemplateUrl,
    openFile,
    openDocument,
    openSourceFile,
    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'

Getting Started

API Reference

Core Concepts

Single-Tenant

Cookbooks

NPM SDK Reference

Integrations

Deployment

npm SDK API Reference

npm SDK API Reference

Backward compatibility

`getTemplateResource(options)`

Getting a `resourceId`

`getTemplateUrl(options)` (deprecated)

`getDocumentSources(options)`

`getDocumentSourceResource(options)`

`getDocumentSourceUrl(options)` (deprecated)

`createDocumentFileSession(options)`

`openDocument(options)`

`openSourceFile(options)`

`openFile(options)`

`generateOnlyOfficeConfig(options)` (lower-level)

OnlyOffice opening flow

`mode` values and editing behavior

Save synchronization

`getDocumentPresignedUrl(options)` (deprecated)

`generateProxyUrl(options)` (deprecated)

`getSectionRules(options)`

TypeScript imports

​npm SDK API Reference

​Backward compatibility

​getTemplateResource(options)

​Getting a resourceId

​getTemplateUrl(options) (deprecated)

​getDocumentSources(options)

​getDocumentSourceResource(options)

​getDocumentSourceUrl(options) (deprecated)

​createDocumentFileSession(options)

​openDocument(options)

​openSourceFile(options)

​openFile(options)

​generateOnlyOfficeConfig(options) (lower-level)

​OnlyOffice opening flow

​mode values and editing behavior

​Save synchronization

​getDocumentPresignedUrl(options) (deprecated)

​generateProxyUrl(options) (deprecated)

​getSectionRules(options)

​TypeScript imports

npm SDK API Reference

Backward compatibility

`getTemplateResource(options)`

Getting a `resourceId`

`getTemplateUrl(options)` (deprecated)

`getDocumentSources(options)`

`getDocumentSourceResource(options)`

`getDocumentSourceUrl(options)` (deprecated)

`createDocumentFileSession(options)`

`openDocument(options)`

`openSourceFile(options)`

`openFile(options)`

`generateOnlyOfficeConfig(options)` (lower-level)

OnlyOffice opening flow

`mode` values and editing behavior

Save synchronization

`getDocumentPresignedUrl(options)` (deprecated)

`generateProxyUrl(options)` (deprecated)

`getSectionRules(options)`

TypeScript imports