JavaScript API¶

The accsyn JavaScript API is the same workspace API as the Python API, for Node.js 18+ and for browsers.

Important Note: API is NOT available for Cloud Essentials or BYOS Lite type workspaces.

How to create and manage API keys¶

API keys are created the same way as for the Python API. See How to create and manage API keys.

Install¶

npm install accsyn

Using¶

Create one session and reuse it. Workspace backends rate-limit REST calls per IP.

import { Session } from "accsyn";

const session = await Session.connect({
  workspace: "acmefilm",
  username: "john@user.com",
  apiKey: process.env.ACCSYN_API_KEY,
});

const job = await session.create("transfer", {
  source: "volume=projects/A001_C064_09224Y_001.mp4",
  destination: "client=664f53b16aa9149860da9d9c:/tmp/A001_C064_09224Y_001.mp4",
});

On Node, workspace, username, and apiKey can be omitted when ACCSYN_WORKSPACE, ACCSYN_API_USER, and ACCSYN_API_KEY are set.

The API queues transfers. It does not move the file bytes itself.

Source code¶

https://github.com/accsyn/javascript-api

Further resources¶

Job JSON Spec

Tutorial | Remote Office Sync

API reference¶

Classes¶

AccsynError¶

Error raised when an accsyn API call fails.

Extends¶

Error

Constructors¶

Constructor¶

new AccsynError(message): AccsynError

# Parameters¶

# message¶

string

# Returns¶

AccsynError

# Overrides¶

Error.constructor

Properties¶

cause?¶

optional cause?: unknown

# Inherited from¶

Error.cause

message¶

message: string

# Inherited from¶

Error.message

name¶

name: string

# Inherited from¶

Error.name

stack?¶

optional stack?: string

# Inherited from¶

Error.stack

stackTraceLimit¶

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

# Inherited from¶

Error.stackTraceLimit

Methods¶

captureStackTrace()¶

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

# Parameters¶

# targetObject¶

object

# constructorOpt?¶

Function

# Returns¶

void

# Inherited from¶

Error.captureStackTrace

prepareStackTrace()¶

static prepareStackTrace(err, stackTraces): any

# Parameters¶

# err¶

Error

# stackTraces¶

CallSite[]

# Returns¶

any

# See¶

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

# Inherited from¶

Error.prepareStackTrace

Session¶

accsyn API session.

Create one with Session.connect and reuse it. Workspace backends rate-limit REST traffic per IP.

Properties¶

connectTimeout¶

readonly connectTimeout: number

timeout¶

readonly timeout: number

username¶

readonly username: string

Methods¶

access()¶

access(targetType, targetId, options?): Promise\<Entity[]>

List recipients on a delivery, or ACL entries on a share.

# Parameters¶

# targetType¶

string

# targetId¶

string

# options?¶

AccessOptions = {}

# Returns¶

Promise\<Entity[]>

activateOne()¶

activateOne(entityType, entityIdent): Promise\<unknown>

Bring a deactivated entity back. entityIdent may be an id or a code.

# Parameters¶

# entityType¶

string

# entityIdent¶

string

# Returns¶

Promise\<unknown>

appIsRunning()¶

appIsRunning(): Promise\<boolean | null>

Whether the desktop app is online on this machine for the logged-in user.

# Returns¶

Promise\<boolean | null>

assign()¶

assign(parentType, entityType, data): Promise\<unknown>

Assign a server or client to a volume or share.

# Parameters¶

# parentType¶

string

# entityType¶

string

# data¶

JsonObject

# Returns¶

Promise\<unknown>

assignments()¶

assignments(entityType, entityId): Promise\<Entity[]>

List servers assigned to a volume or share.

# Parameters¶

# entityType¶

string

# entityId¶

string

# Returns¶

Promise\<Entity[]>

create()¶

create(entityType, data, options?): Promise\<Entity | Entity[]>

Create an entity.

data may be an object, a list of tasks, a JSON string, or (on Node) a path to a JSON file.

# Parameters¶

# entityType¶

string

# data¶

CreateData

# options?¶

CreateOptions = {}

# Returns¶

Promise\<Entity | Entity[]>

daemonIsRunning()¶

daemonIsRunning(): Promise\<boolean | null>

Whether a server or user-server daemon is online on this machine for the logged-in user.

# Returns¶

Promise\<boolean | null>

deactivateOne()¶

deactivateOne(entityType, entityId): Promise\<unknown>

Deactivate an entity, keeping it for audit.

# Parameters¶

# entityType¶

string

# entityId¶

string

# Returns¶

Promise\<unknown>

deassign()¶

deassign(parentType, entityType, data): Promise\<unknown>

Remove a server assignment from a volume or share.

# Parameters¶

# parentType¶

string

# entityType¶

string

# data¶

JsonObject

# Returns¶

Promise\<unknown>

delete()¶

delete(path, force?): Promise\<unknown>

Delete a file or directory on a share. Set force to remove a non-empty directory.

# Parameters¶

# path¶

FilePath

# force?¶

boolean = false

# Returns¶

Promise\<unknown>

deleteMany()¶

deleteMany(entityType, entityId, data): Promise\<unknown>

Delete files beneath a collection.

# Parameters¶

# entityType¶

string

# entityId¶

string

# data¶

JsonObject

# Returns¶

Promise\<unknown>

deleteOne()¶

deleteOne(entityType, entityId, data?): Promise\<unknown>

Archive an entity. ACLs must be removed with Session.revoke.

# Parameters¶

# entityType¶

string

# entityId¶

string

# data?¶

JsonObject | null

# Returns¶

Promise\<unknown>

deleteSetting()¶

deleteSetting(entityType, name, entityId?): Promise\<boolean>

Delete a setting.

# Parameters¶

# entityType¶

string

# name¶

string

# entityId?¶

string | null

# Returns¶

Promise\<boolean>

exists()¶

exists(path): Promise\<unknown>

Whether a share path exists.

# Parameters¶

# path¶

FilePath

# Returns¶

Promise\<unknown>

find()¶

find(query, options?): Promise\<Entity | Entity[] | null>

Query entities, entitytypes, or attributes.

# Parameters¶

# query¶

string

# options?¶

FindOptions = {}

# Returns¶

Promise\<Entity | Entity[] | null>

findOne()¶

findOne(query, options?): Promise\<Entity | null>

Return a single entity, or null.

# Parameters¶

# query¶

string

# options?¶

Omit\<FindOptions, "singleEntityQuery" | "limit" | "skip" | "create" | "update"> = {}

# Returns¶

Promise\<Entity | null>

getApiKey()¶

getApiKey(): Promise\<string>

Fetch the user API key. Often disabled server-side.

# Returns¶

Promise\<string>

getEntity()¶

getEntity(entityType, entityId): Promise\<Entity | null>

Fetch an entity by type and 24-character id, including inactive and archived records.

# Parameters¶

# entityType¶

string

# entityId¶

string

# Returns¶

Promise\<Entity | null>

getLastMessage()¶

getLastMessage(): string | null

Error message from the last failed API call, if any.

# Returns¶

string | null

getSetting()¶

getSetting(name?, options?): Promise\<unknown>

Read one setting value.

# Parameters¶

# name?¶

string | null

# options?¶

SettingScope = {}

# Returns¶

Promise\<unknown>

getSettings()¶

getSettings(options?): Promise\<JsonObject>

Read the settings object for an entity. Defaults to the workspace.

# Parameters¶

# options?¶

SettingsOptions = {}

# Returns¶

Promise\<JsonObject>

getSize()¶

getSize(path, include?, exclude?): Promise\<unknown>

Size of a file or directory on a share.

# Parameters¶

# path¶

FilePath

# include?¶

string | string[]

# exclude?¶

string | string[]

# Returns¶

Promise\<unknown>

grant()¶

grant(entityType, entityId, targetType, targetId, data?): Promise\<unknown>

Grant a user access to a delivery, request, stream, or share. entityType must be user. entityId may be an id or, for unique types, a code such as an email.

# Parameters¶

# entityType¶

string

# entityId¶

string

# targetType¶

string

# targetId¶

string

# data?¶

JsonObject | null

# Returns¶

Promise\<unknown>

integration()¶

integration(name, operation, data): Promise\<unknown>

Call an integration utility.

# Parameters¶

# name¶

string

# operation¶

string

# data¶

JsonObject

# Returns¶

Promise\<unknown>

logs()¶

logs(options?): Promise\<JsonObject>

Backend disk logs for an entity scope.

# Parameters¶

# options?¶

LogOptions = {}

# Returns¶

Promise\<JsonObject>

ls()¶

ls(path, options?): Promise\<unknown>

List files on a share. path uses the form share=<share>/<path>.

# Parameters¶

# path¶

FilePath

# options?¶

FileListOptions = {}

# Returns¶

Promise\<unknown>

metrics()¶

metrics(query, attributes?, time?): Promise\<JsonObject>

Metrics for an entity query, typically a job.

# Parameters¶

# query¶

string

# attributes?¶

string[] | null

# time?¶

string | null

# Returns¶

Promise\<JsonObject>

mkdir()¶

mkdir(path): Promise\<unknown>

Create a directory on a share.

# Parameters¶

# path¶

FilePath

# Returns¶

Promise\<unknown>

move()¶

move(pathSrc, pathDst): Promise\<unknown>

Move a file or directory on a share.

# Parameters¶

# pathSrc¶

FilePath

# pathDst¶

FilePath

# Returns¶

Promise\<unknown>

prepublish()¶

prepublish(data): Promise\<unknown>

Pre-process a publish file list. Directory sizes are filled in when omitted.

# Parameters¶

# data¶

JsonObject[]

# Returns¶

Promise\<unknown>

rename()¶

rename(path, pathTo): Promise\<unknown>

Rename a file or directory within the same parent directory.

# Parameters¶

# path¶

FilePath

# pathTo¶

FilePath

# Returns¶

Promise\<unknown>

report()¶

report(query): Promise\<string>

Support report for an entity query.

# Parameters¶

# query¶

string

# Returns¶

Promise\<string>

revoke()¶

revoke(entityType, entityId, targetType, targetId): Promise\<unknown>

Revoke a user's access. Returns false when no matching recipient or ACL exists.

# Parameters¶

# entityType¶

string

# entityId¶

string

# targetType¶

string

# targetId¶

string

# Returns¶

Promise\<unknown>

setSetting()¶

setSetting(entityType, name, value, entityId?): Promise\<boolean>

Set a setting. value must already be a string; serialize objects and dates first.

# Parameters¶

# entityType¶

string

# name¶

string

# value¶

string

# entityId?¶

string | null

# Returns¶

Promise\<boolean>

update()¶

update(entityType, entityId, data): Promise\<Entity | undefined>

Update one entity. ACLs must be changed with Session.grant.

# Parameters¶

# entityType¶

string

# entityId¶

string

# data¶

JsonObject

# Returns¶

Promise\<Entity | undefined>

updateMany()¶

updateMany(entityType, entityId, data): Promise\<Entity[] | undefined>

Update tasks beneath a job. entityType must be task.

# Parameters¶

# entityType¶

string

# entityId¶

string

# data¶

JsonObject[]

# Returns¶

Promise\<Entity[] | undefined>

connect()¶

static connect(options?): Promise\<Session>

Authenticate and open a session.

On Node, omitted credentials are read from the environment or a .env file.

# Parameters¶

# options?¶

SessionOptions = {}

# Returns¶

Promise\<Session>

getHostname()¶

static getHostname(): Promise\<string>

Hostname of this computer. Returns unknown in the browser.

# Returns¶

Promise\<string>

Interfaces¶

AccessOptions¶

Properties¶

entityId?¶

optional entityId?: string

entityType?¶

optional entityType?: string

recursive?¶

optional recursive?: boolean

CreateOptions¶

Properties¶

allowDuplicates?¶

optional allowDuplicates?: boolean

Allow duplicate tasks and retry the existing task.

entityId?¶

optional entityId?: string

Parent id when creating sub-entities such as tasks.

replaceDuplicates?¶

optional replaceDuplicates?: boolean

Replace duplicate tasks instead of retrying them.

Entity¶

JSON object returned by the accsyn backend.

Indexable¶

[key: string]: unknown

Properties¶

id?¶

optional id?: string

FileListOptions¶

Properties¶

directoriesOnly?¶

optional directoriesOnly?: boolean

exclude?¶

optional exclude?: string | string[]

filesOnly?¶

optional filesOnly?: boolean

getSize?¶

optional getSize?: boolean

include?¶

optional include?: string | string[]

maxDepth?¶

optional maxDepth?: number

recursive?¶

optional recursive?: boolean

FindOptions¶

Properties¶

archived?¶

optional archived?: boolean

attributes?¶

optional attributes?: string[]

create?¶

optional create?: boolean

When querying attributes, return create attributes.

entityId?¶

optional entityId?: string

finished?¶

optional finished?: boolean

inactive?¶

optional inactive?: boolean

limit?¶

optional limit?: number

offline?¶

optional offline?: boolean

# Deprecated¶

Use inactive.

singleEntityQuery?¶

optional singleEntityQuery?: boolean

skip?¶

optional skip?: number

update?¶

optional update?: boolean

When querying attributes, return update attributes.

LogOptions¶

Properties¶

entityId?¶

optional entityId?: string | null

entityType?¶

optional entityType?: string | null

paginationLimit?¶

optional paginationLimit?: number

paginationPage?¶

optional paginationPage?: number

paginationSkip?¶

optional paginationSkip?: number

search?¶

optional search?: string

sort?¶

optional sort?: string

sortReverse?¶

optional sortReverse?: boolean

SessionOptions¶

Properties¶

apiKey?¶

optional apiKey?: string

API key. Falls back to ACCSYN_API_KEY.

connectTimeout?¶

optional connectTimeout?: number

Connection timeout in seconds. Defaults to 10. Recorded for parity; fetch uses timeout as the abort deadline.

domain?¶

optional domain?: string

# Deprecated¶

Use workspace.

hostname?¶

optional hostname?: string

Override the workspace hostname.

pathEnvfile?¶

optional pathEnvfile?: string

Path to a .env file. Falls back to ACCSYN_CREDENTIALS_PATH, then ./.env on Node.

port?¶

optional port?: number

Override the workspace port. Defaults to 443.

prettyJson?¶

optional prettyJson?: boolean

Pretty-print JSON in verbose logs.

proxy?¶

optional proxy?: string

Proxy setting. Falls back to ACCSYN_PROXY. SOCKS proxies are not supported.

timeout?¶

optional timeout?: number

Response timeout in seconds. Defaults to 120.

username?¶

optional username?: string

User email. Falls back to ACCSYN_API_USER.

verbose?¶

optional verbose?: boolean

Print REST traffic to the console.

workspace?¶

optional workspace?: string

Workspace code. Falls back to ACCSYN_WORKSPACE, ACCSYN_DOMAIN, then ACCSYN_ORG.

SettingScope¶

Properties¶

data?¶

optional data?: JsonObject | null

entityId?¶

optional entityId?: string | null

entityType?¶

optional entityType?: string

integration?¶

optional integration?: string

SettingsOptions¶

Properties¶

entityId?¶

optional entityId?: string | null

entityType?¶

optional entityType?: string | null

omitDefaults?¶

optional omitDefaults?: boolean

recursive?¶

optional recursive?: boolean

optional share?: string

upstream?¶

optional upstream?: boolean

Type Aliases¶

CreateData¶

CreateData = string | JsonObject | JsonObject[]

FilePath¶

FilePath = string | JsonObject | string[]

JsonObject¶

JsonObject = Record\<string, unknown>

Variables¶

ACCSYN_BACKEND_DOMAIN¶

const ACCSYN_BACKEND_DOMAIN: "accsyn.com" = "accsyn.com"

ACCSYN_BACKEND_MASTER_HOSTNAME¶

const ACCSYN_BACKEND_MASTER_HOSTNAME: "master.accsyn.com"

ACCSYN_PORT¶

const ACCSYN_PORT: 443 = 443

CLEARANCE_ADMIN¶

const CLEARANCE_ADMIN: "admin" = "admin"

CLEARANCE_EMPLOYEE¶

const CLEARANCE_EMPLOYEE: "employee" = "employee"

CLEARANCE_NONE¶

const CLEARANCE_NONE: "none" = "none"

CLEARANCE_STANDARD¶

const CLEARANCE_STANDARD: "standard" = "standard"

CLEARANCE_SUPPORT¶

const CLEARANCE_SUPPORT: "support" = "support"

CLIENT_STATE_DISABLED¶

const CLIENT_STATE_DISABLED: "disabled" = "disabled"

CLIENT_STATE_DISABLED_OFFLINE¶

const CLIENT_STATE_DISABLED_OFFLINE: "disabled-offline" = "disabled-offline"

CLIENT_STATE_INIT¶

const CLIENT_STATE_INIT: "init" = "init"

CLIENT_STATE_OFFLINE¶

const CLIENT_STATE_OFFLINE: "offline" = "offline"

CLIENT_STATE_ONLINE¶

const CLIENT_STATE_ONLINE: "online" = "online"

CLIENT_TYPE_ACCSYN_VPX¶

const CLIENT_TYPE_ACCSYN_VPX: 5 = 5

CLIENT_TYPE_APP¶

const CLIENT_TYPE_APP: 0 = 0

CLIENT_TYPE_BROWSER¶

const CLIENT_TYPE_BROWSER: 3 = 3

CLIENT_TYPE_COMPUTE_LANE¶

const CLIENT_TYPE_COMPUTE_LANE: 4 = 4

CLIENT_TYPE_SERVER¶

const CLIENT_TYPE_SERVER: 1 = 1

CLIENT_TYPE_USERSERVER¶

const CLIENT_TYPE_USERSERVER: 2 = 2

JOB_TYPE_COMPUTE¶

const JOB_TYPE_COMPUTE: 3 = 3

JOB_TYPE_DELIVERY¶

const JOB_TYPE_DELIVERY: 7 = 7

JOB_TYPE_QUEUE¶

const JOB_TYPE_QUEUE: 2 = 2

JOB_TYPE_REQUEST¶

const JOB_TYPE_REQUEST: 8 = 8

JOB_TYPE_STREAM¶

const JOB_TYPE_STREAM: 10 = 10

JOB_TYPE_TRANSFER¶

const JOB_TYPE_TRANSFER: 1 = 1

UNIQUE_ENTITY_TYPES¶

const UNIQUE_ENTITY_TYPES: readonly ["user", "workspace", "share", "volume", "folder", "home", "collection", "site", "engine", "queue"]

VERSION¶

const VERSION: "3.4.0" = "3.4.0"

Package version. Matches accsyn-python-api 3.4.0.