Abstract SDK

Abstract SDK

  • Getting started
  • API Reference

›API Reference

Getting Started

  • Installation
  • Authentication
  • Configuration
  • Usage

Concepts

  • Rate limits
  • Transports
  • Pagination
  • Webhooks
  • Webhooks Security
  • Full Responses
  • Latest commits
  • Embeds

API Reference

  • Client
  • Sketch
Edit

Client

Activities

An activity represents a designated type of event within a project. These events can be specific to the project itself, or they can be specific to a collection, a branch, a commit, or a review within the project.

The activity object

PropertyTypeDescription
branchIdstringUUID of the branch that this activity was triggered on
createdAtstringTimestamp at which the activity was triggered
idstringUUID identifier of the activity
payloadObjectObject containing information specific to this type of activity
typestringThe type of this activity, may be one of BRANCH_ARCHIVED, BRANCH_CREATED, BRANCH_DELETED, BRANCH_DESCRIPTION_UPDATED, BRANCH_RENAMED, BRANCH_STATUS_UPDATED, BRANCH_UNARCHIVED, COLLECTION_PUBLISHED, COMMENT_CREATED, COMMIT, MERGE_COMMIT, PROJECT_ARCHIVED, PROJECT_CREATED, PROJECT_DELETED, PROJECT_DESCRIPTION_CHANGED, PROJECT_RENAMED, PROJECT_TRANSFERRED, PROJECT_UNARCHIVED, REVIEWER_REMOVED, REVIEW_COMPLETED, REVIEW_DISMISSED, REVIEW_REQUESTED, UPDATE_COMMIT
userIdstringUUID of the user that triggered this activity

List all activities

API

activities.list(BranchDescriptor | OrganizationDescriptor | ProjectDescriptor, ListOptions): CursorPromise<Activity[]>

List the first two activities for a given project on a specific branch

abstract.activities.list({
  branchId: "8a13eb62-a42f-435f-b3a3-39af939ad31b",
  projectId: "b8bf5540-6e1e-11e6-8526-2d315b6ef48f",
}, { limit: 2 });

Note: This endpoint returns a special type of Promise called a CursorPromise that supports cursor-based pagination. Additional information can be found here.

Retrieve an activity

API

activities.info(ActivityDescriptor, RequestOptions): Promise<Activity>

Load the info for an activity

abstract.activities.info({
  activityId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Assets

An asset represents a resource exported from a design file. Assets are automatically updated and available for new commits.

Note: Assets are only supported when using a Business or Enterprise plan. More information on Abstract plan types can be found here.

The asset object

PropertyTypeDescription
createdAtstringTimestamp at which the asset was created
defaultAbstractFormatbooleanIndicates if this asset is the default asset for a layer
fileFormatstringFile type of this asset
fileIdstringFile ID of this asset
formatNamestringFormat of this file, e.g. "2x"
idstringUUID identifier of the asset
layerIdstringUUID of the layer this asset belongs to
layerNamestringName of the layer this asset belongs to
namingSchemestringDetermines how the formatName is applied when constructing the filename for this asset. "1" means the formatName will be used as a prefix, "0" means it will be used as a suffix.
nestedLayerIdstringID of the nested layer this asset belongs to
projectIdstringID of the project this asset belongs to
scalestringScale of this asset in Sketch, e.g. "1.00"
shastringSHA of the commit containing the version of the file this asset belongs to
urlstringDirect URL to the asset file

Retrieve an asset

API

asset.info(AssetDescriptor, RequestOptions): Promise<Asset>

Load the info for an asset

abstract.assets.info({
  assetId: "fcd67bab-e5c3-4679-b879-daa5d5746cc2",
  projectId: "b8bf5540-6e1e-11e6-8526-2d315b6ef48f"
});

List assets for a file

API

assets.file(FileDescriptor, ListOptions): CursorPromise<Asset[]>

List the first ten assets for a given file

abstract.assets.file({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  sha: "latest"
}, {
  limit: 10
});

Note: This endpoint returns a special type of Promise called a CursorPromise that supports cursor-based pagination. More information can be found here.

List assets for a commit

assets.commit(BranchCommitDescriptor, RequestOptions): Promise<Asset[]>

List all assets generated for a commit

abstract.assets.commit({
  branchId: "8a13eb62-a42f-435f-b3a3-39af939ad31b",
  projectId: "b8bf5540-6e1e-11e6-8526-2d315b6ef48f",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a", // or sha: "latest"
});

Export an asset file

API

asset.raw(AssetDescriptor, RawOptions}): Promise<ArrayBuffer>

Retrieve a given asset file based on its ID and save it to disk. Files will be saved to the current working directory by default, but a custom filename option can be used to customize this location, or disableWrite can be used to disable automatic saving altogether.

abstract.assets.raw({
  assetId: "fcd67bab-e5c3-4679-b879-daa5d5746cc2",
  projectId: "b8bf5540-6e1e-11e6-8526-2d315b6ef48f"
});

The resulting ArrayBuffer can be also be used with node fs APIs directly. For example, it's possible to write the image to disk manually after post-processing it:

const arrayBuffer = await abstract.assets.raw({
  assetId: "fcd67bab-e5c3-4679-b879-daa5d5746cc2",
  projectId: "b8bf5540-6e1e-11e6-8526-2d315b6ef48f"
}, {
  disableWrite: true
});

processedBuffer = postProcess(arrayBuffer);

fs.writeFile("asset.png", Buffer.from(processedBuffer), (err) => {
  if (err) throw err;
  console.log("Asset image written!");
});

Example: Save all assets for a given file

// Get all assets for a given file
const assets = await abstract.assets.file({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  sha: "latest"
});

// Save the raw file for each asset to the current working directory
await Promise.all(assets.map(asset => abstract.assets.raw({
    id: asset.id,
    projectId: asset.projectId
})));

Branches

A branch is where design work and commits happen. A branch acts as a personal workspace for contributors, we encourage branches to be created for logical chunks of work – for example designing a new feature.

The branch object

PropertyTypeDescription
createdAtstringTimestamp that the branch was created
descriptionstringA summary of the branch – this field may contain markdown.
divergedFromBranchIdstringUUID identifier of the branch this branch diverged from
headstringSHA that represents the latest commit on the branch
idstringUUID identifier of the branch, or the string "master"
mergeShastringSHA that represents the commit where this branch was merged
mergedIntoBranchIdstringUUID identifier of the branch this branch was merged into
namestringThe name of the branch
parentstringUUID identifier of the branch that this branch was created from, or the string "master"
projectIdstringUUID of the project that this branch is contained within
startedAtShastringSHA that represents the commit where this branch was created
statusstringThe current status of the branch. May be one of active, wip, feedback, review, merged, archived, deleted, diverged
updatedAtstringTimestamp that the branch was last updated
userIdstringUUID of the user that created the branch
userNamestringThe name of the user that created the branch

List all branches

CLI API

branches.list(ProjectDescriptor, { ...RequestOptions, filter?: "active" | "archived" | "mine", search?: string }): Promise<Branch[]>

List the active branches for a project

abstract.branches.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
}, {
  filter: "active"
});

List all active branches for a user in a project

abstract.branches.list({
  userId: "48b5d670-2002-45ea-929d-4b00863778e4",
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
}, {
  filter: "active"
});

List all branches for a user across all organizations

abstract.branches.list({
  userId: "48b5d670-2002-45ea-929d-4b00863778e4"
});

Search for a branch by name across all projects

abstract.branches.list(undefined, {
  search: "branch name"
});

Note: Searching for branches is only available when using the API transport.

Retrieve a branch

CLI API

branches.info(BranchDescriptor, RequestOptions): Promise<Branch>

Load the info for a specific branch in a project

abstract.branches.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
});

BranchMergeState

A branch merge state is a description of whether a branch can be cleanly merged to its parent branch.

The branch merge state object

PropertyTypeDescription
statestringThe merge state of the branch relative to its parent branch. May be one of CLEAN, NEEDS_UPDATE, or NEEDS_REMOTE_UPDATE
parentIdstringUUID of the parent branch
parentCommitstringSHA that represents the latest commit on the parent branch
branchIdstringUUID identifier of the branch, or the string "master"
branchCommitstringSHA that represents the latest commit on the branch
aheadnumberThe number of commits that the branch is ahead of its parent
behindnumberThe number of commits that the branch is behind its parent

Merge state of a branch

CLI API

branches.mergeState(BranchDescriptor, { ...RequestOptions, parentId?: string }): Promise<BranchMergeState>

Load the merge state for a specific branch in a project.

abstract.branches.mergeState({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "252e9141-5cfc-4f4e-823b-a85f4cfd9a32"
});

Note: The API and CLI transports behave differently for merge state. The CLI transport ignores options.parentId, and only returns one of the three possible merge states (no other fields are included). The API transport includes a value for each field of BranchMergeState, and only returns statuses CLEAN or NEEDS_UPDATE.

Update a branch

CLI API

branches.update(BranchDescriptor, BranchInput, RequestOptions): Promise<Branch>

Update an existing branch

abstract.branches.update({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
}, {
  name: "New name",
  description: "New description",
  status: "development"
});

Changesets

A changeset is a group of changes that together form a single, indivisible modification to a project. Changesets include data on all visual and nonvisual changes and provide insight into the differences between two versions of a project.

The Changeset object

PropertyTypeDescription
branchIdstringUUID of the branch that this changeset is part of, or the string "master"
changesChangesetChange[]List of changes that make up this changeset
compareToShastring
SHA of the commit introducing changes in this changeset
idstringUUID identifier of the changeset
projectIdstringUUID of the project this changeset belongs to
shastringSHA of the base commit in this changeset that changes are against

The ChangesetChange object

PropertyTypeDescription
typestringType of this change, can be one of file, page, layer, symbol, artboard, colors, gradient, layer-style, text-style
statusstringStatus of this change, can be one of added, deleted, edited, edited-indirectly, none
hasPreviewbooleanIndicates if this change has a visual preview
meta{ [key: string]: [any, any] }Object containing additional information about this change
fileIdstringUUID of the file this change was made against
pageIdstringUUID of the page this change was made against
layerIdstringUUID of the layer this change was made against
colorsIdstringUUID of the color associated with this change
gradientIdstringUUID of the gradient associated with this change
layerStyleIdstringUUID of the layer style associated with this change
textStyleIdstringUUID of the text style associated with this change

Retrieve a changeset for a commit

CLI API

changesets.commit(BranchCommitDescriptor, RequestOptions): Promise<Changeset>

Load a changeset for a commit

abstract.changesets.commit({
  branchId: "master",
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  sha: "e2a0a301c4a530ec16024cbb339dfc135c841b10"
});

Retrieve a changeset for a branch

CLI API

changesets.commit(BranchDscriptor, RequestOptions): Promise<Changeset>

Load a changeset for a branch

abstract.changesets.branch({
  branchId: "c426d0a6-e039-43d7-b7b3-e685a25e4cfb",
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Collections

A collection is a set of layers at the same or different commits on a branch, they can be created in the desktop or web app and are used to group work together to communicate a flow, ask for review, or other use cases.

The collection object

PropertyTypeDescription
branchIdstringUUID of the branch that this collection belongs to, or the string "master"
createdAtstringTimestamp that the collection was created
descriptionstringA description of the collection
idstringUUID identifier of the collection
layersCollectionLayer[]An ordered array of collection layers. Note: These are not the same as Layer objects.
namestringThe name of the collection
projectIdstringUUID of the project this commit belongs to
publishedAtstringTimestamp that the collection was published
userUserThe user that created the collection
userIdstringUUID of the user that created the collection

List all collections

CLI API

collections.list(ProjectDescriptor | BranchDescriptor, CollectionsListOptions): Promise<Collection[]>

List all collections for a branch

abstract.collections.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
});

Search and sort specific collections

abstract.collections.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
}, {
  branchStatus: "active",
  layersPerCollection: 5,
  search: "search string",
  sortBy: "updatedAt"
});

s

Note: Collection searching and sorting is only available when using the API transport.

Retrieve a collection

CLI API

collections.info(CollectionDescriptor, RequestOptions): Promise<Collection>

Load an individual collection

abstract.collections.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  collectionId: "413daa80-1456-11e8-b8b0-4d1fec7ae555"
});

Create a collection

CLI API

collections.create(ProjectDescriptor, NewCollection, RequestOptions): Promise<Collection>

Create a new collection

abstract.collections.create({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
}, {
  name: "Test collection",
  description: "Test description",
  branchId: "c426d0a6-e039-43d7-b7b3-e685a25e4cfb"
});

Update a collection

CLI API

collections.update(CollectionDescriptor, UpdatedCollection, RequestOptions): Promise<Collection>

Update an existing collection

abstract.collections.update({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  collectionId: "413daa80-1456-11e8-b8b0-4d1fec7ae555"
}, {
  name: "New name"
});

CollectionLayers

A collection layer represents an underlying layer within a collection. Collection layers can be added to, removed from, and updated within existing collections.

The CollectionLayer object

PropertyTypeDescription
collectionIdstringUUID of the collection that this collection layer is part of
fileIdstringUUID of the file that the underlying layer is part of
pageIdstringUUID of the page that the underlying layer is part of
layerIdstringUUID of the underlying layer that this collection layer represents
projectIdstringUUID of the project that this collection layer is contained within
isPinnedbooleanSHA of the commit introducing changes in this changeset
useLatestCommitbooleanDetermines if this collection layer should always point to the latest version of its underlying layer
idstringUUID identifier of this collection layer
ordernumberSHA of the commit that the underlying layer should point to
shastringSHA of the commit that the underlying layer should point to

The NewCollectionLayer object

PropertyTypeDescription
fileIdstringUUID of the file that the underlying layer is part of
pageIdstringUUID of the page that the underlying layer is part of
layerIdstringUUID of the underlying layer that this collection layer represents
isPinnedbooleanSHA of the commit introducing changes in this changeset
useLatestCommitbooleanDetermines if this collection layer should always point to the latest version of its underlying layer
ordernumberSHA of the commit that the underlying layer should point to
shastringSHA of the commit that the underlying layer should point to

Add a single layer to a collection

API

collectionLayers.add(CollectionDescriptor, NewCollectionLayer, RequestOptions): Promise<CollectionLayer>

Add a single layer to a collection

abstract.collectionLayers.add({
    projectId: '003a1ae0-a4b3-11e9-807c-a35b74e69da5',
    collectionId: '2538be75-c38b-4008-8a60-cf2c0364727e'
}, {
    fileId: '745EF992-C945-4B4C-BAFD-C6D45C45C6E2',
    isPinned: true,
    layerId: '9E2EB6C6-3681-4FCF-951E-50F7F0A0B0DE',
    order: 1,
    pageId: '7DC19A61-4D5F-4D75-BCAE-A589DF08257B',
    sha: 'latest'
});

Add multiple layers to a collection

API

collectionLayers.addMany(CollectionDescriptor, NewCollectionLayer[], RequestOptions): Promise<CollectionLayer[]>

Add multiple layers to a collection

abstract.collectionLayers.addMany({
    projectId: '003a1ae0-a4b3-11e9-807c-a35b74e69da5',
    collectionId: '2538be75-c38b-4008-8a60-cf2c0364727e'
}, [
  {
    fileId: '745EF992-C945-4B4C-BAFD-C6D45C45C6E2',
    isPinned: true,
    layerId: '9E2EB6C6-3681-4FCF-951E-50F7F0A0B0DE',
    order: 1,
    pageId: '7DC19A61-4D5F-4D75-BCAE-A589DF08257B',
    sha: 'latest'
  }
]);

Remove a layer from a collection

API

collectionLayers.remove(CollectionLayerDescriptor, RequestOptions): Promise<void>

Remove a layer from a collection

abstract.collectionLayers.remove({
    projectId: '003a1ae0-a4b3-11e9-807c-a35b74e69da5',
    collectionLayerId: '8a2aaa0f-bc8e-4b0d-9f79-dda1c68f12f1'
});

Update a layer within a collection

API

collectionLayers.update(CollectionLayerDescriptor, UpdatedCollectionLayer, RequestOptions): Promise<CollectionLayer>

Update a layer within a collection

abstract.collectionLayers.update({
    projectId: '003a1ae0-a4b3-11e9-807c-a35b74e69da5',
    collectionLayerId: '8a2aaa0f-bc8e-4b0d-9f79-dda1c68f12f1'
}, {
    fileId: '745EF992-C945-4B4C-BAFD-C6D45C45C6E2',
    isPinned: false,
    layerId: '9E2EB6C6-3681-4FCF-951E-50F7F0A0B0DE',
    order: 2,
    pageId: '7DC19A61-4D5F-4D75-BCAE-A589DF08257B',
    sha: 'latest'
});

Reorder a layer within a collection

API

collectionLayers.move(CollectionLayerDescriptor, number, RequestOptions): Promise<CollectionLayer[]>

Reorder a layer within a collection

abstract.collectionLayers.move({
    projectId: '003a1ae0-a4b3-11e9-807c-a35b74e69da5',
    collectionLayerId: '8a2aaa0f-bc8e-4b0d-9f79-dda1c68f12f1'
}, 2);

Comments

A comment in Abstract can be left on a branch, commit, or layer. Comments on layers can also include an optional annotation that represents a bounding area on-top of the layer, this can be used to leave comments about specific areas.

The comment object

PropertyTypeDescription
annotationAnnotationThe optional bounding box for the comment on the layer
bodystringThe body of the comment
branchIdstringUUID of the branch this comment is on, or the string "master"
commitShastringSHA of the commit this comment was left on
createdAtstringTimestamp of the comment creation time
deletedAtstringTimestamp of the comment deletion time
editedAtstringTimestamp of when the comment was last edited
fileIdstringUUID of the file that this comment is on
idstringUUID identifier of the comment
layerIdstringUUID of the layer that this comment is on
pageIdstringUUID of the page that this comment is on
parentIdstringUUID of the parent comment if this is a reply
projectIdstringUUID of the project that this comment is contained within
replyIdsstring[]An array of comment UUID's that are replies to this comment
reviewStatusstringIf the comment was a review this may be one of APPROVED or REJECTED
updatedAtstringTimestamp of when the comment was last updated
userUserThe user that created the comment
userIdstringUUID of the user this commit was created by

List all comments

API

comments.list(BranchDescriptor | BranchCommitDescriptor | PageDescriptor | LayerVersionDescriptor, RequestOptions): CursorPromise<Comment[]>

List the comments for a specific project

abstract.comments.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

or, list the first two comments for a specific layer...

abstract.comments.list({
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
}, { limit: 2 });

Note: This endpoint returns a special type of Promise called a CursorPromise that supports cursor-based pagination. More information can be found here.

Retrieve a comment

API

comments.info(CommentDescriptor, RequestOptions): Promise<Comment>

Load the info for a comment

abstract.comments.info({
  commentId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Create a comment

API

comments.create(BranchDescriptor | BranchCommitDescriptor | LayerVersionDescriptor, Comment, RequestOptions): Promise<Comment>

Create a comment on a branch

abstract.comments.create({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
}, {
  body: "Hello from the Abstract SDK"
});

Or, perhaps create an annotation on a layer…

abstract.comments.create({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a", // or sha: "latest"
}, {
  body: "Hello from the Abstract SDK",
  annotation: {
    width: 100,
    height: 100,
    x: 300,
    y: 400
  }
});

Note: It's important to ensure that the annotation bounding box is within the dimensions of the layer!

Commits

A commit represents a point in time – contributors can create commits in the desktop app to save their work at different stages. When loading data from the Abstract SDK you will almost always need to provide a commit SHA to identify which version of the object you would like.

The commit object

PropertyTypeDescription
descriptionstringThe body of the commit comment
destinationBranchIdstringFor merge commits this points to the merged into branch
destinationBranchNamestringFor merge commits this is the name of the branch that was merged into
fileIdsstring[]For system commits like file upgrades this represents the file UUID's that were changed
parentsstring[]SHA(s) of the parent commits
projectIdstringUUID of the project this commit belongs to
shastringSHA of the hashed content of the commit. This acts as the unique identifer.
sourceBranchIdstringFor merge commits this points to the merged from branch
sourceBranchNamestringFor merge commits this is the name of the branch that was merged from
timestringTimestamp of the commit
titlestringThe title of the commit
typestringThe type of the commit, may be one of NORMAL, PROJECT_CREATED, FILE_ADDED, FILE_RENAMED, FILE_DELETED, FILE_REPLACED, LIBRARY_ADDED, LIBRARY_REMOVED, RESTORE, UPDATE, MERGE
userIdstringUUID of the user this commit was created by
userNamestringDisplay name of the user this commit was created by

List all commits

CLI API

commits.list(BranchDescriptor | FileDescriptor | LayerDescriptor, { ...RequestOptions, limit?: number, startSha?: string, endSha?: string }): Promise<Commit[]>

List the commits for a specific branch

abstract.commits.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
});

or, get a list of commits for a layer – this query will only return commits where the referenced layer was changed…

abstract.commits.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19"
});

Retrieve a commit

CLI API

commits.info (FileDescriptor | LayerVersionDescriptor | CommitDescriptor, RequestOptions): Promise<Commit>

Load the commit info for a specific commit SHA on a branch

abstract.commits.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  sha: "fb7e9b50da6c330fc43ffb369616f0cd1fa92cc2"
});

Data

The LayerDataset object

PropertyTypeDescription
branchIdstringUUID of the branch that this layer is contained within
fileIdstringUUID of the file that this layer is contained within
layerIdstringUUID of the layer that this data is loaded from
layers{string: LayerData }An object that describes the child layers
projectIdstringUUID of the project that this data is contained within
shastringSHA of the commit where the layer was last changed

LayerData

PropertyTypeDescription
childIdsstring[]Array of UUID's for the layers children, if any
idstringUUID of the chid layer
libraryIdstringUUID of the library file this layer is from
libraryNamestringThe name of the library file this layer is from
parentIdstringUUID of the parent layer, if any
propertiesLayerDataPropertiesLayer properties
symbolIdstringUUID of symbol master, if any
typestringOne of artboard, layer, symbolMaster, symbolInstance, group, text, bitmap, shapeGroup, shapePath, rectangle, oval, polygon, triangle, star, page, slice, hotspot

LayerDataProperties

PropertyTypeDescription
namestringName of the layer
isVisiblebooleanIs layer visible in the artboard
isLockedbooleanDetermines whether layer is locked or not
widthnumberThe width of layer in pixels
heightnumberThe height of layer in pixels
xnumberThe relative horizontal position of the layer on the page, measured from the left
ynumberThe relative vertical position of the layer on the page, measured from the top
rotationnumberThe rotation of the layer in degrees
opacitynumberOpacity from 0 to 100
hasClippingMaskbooleanEnsures whether a layer has a clipping mask
underClippingMaskbooleanEnsures whether a layer is under clipping mask or not
textStyleIndexLayerTextStyle[]Styles of Text. Refer to LayerTextStyle
colorIndexLayerColor[]Colors. Refer to LayerColor
blendModeLayerBlendModeRefer to LayerBlendMode
styleName?stringName of layer styles applies to layer
hasClickThrough?booleanCan be clicked when pressing cmd or selecting the "Click-through when selecting"
imageId?stringAn id to image when layer is a bitmap
textContent?stringInner text of a layer
backgroundColor?LayerColorBackground color of a layer. Refer to LayerColor
borderRadius?LayerBorderRadiusThe value of layer's border radius. Refer to LayerBorderRadius
text?LayerTextStyleThe style of text in a layer. Refer to LayerTextStyle
fills?LayerFill[]The fill styles for a layer. Refer to LayerFill
borders?LayerBorder[]Styles for borders. Refer to LayerBorder
shadows?LayerShadowsShadow values. Refer to LayerShadows
resizingConstraint?LayerResizingConstraintRefer to LayerResizingConstraint
overrides?LayerOverrideDataRefer to LayerOverrideData
assets?LayerDataAsset[]A list of assets in a layer. Refer to LayerDataAsset

LayerTextStyle

PropertyTypeDescription
styleName?stringStyle name for text
fixed?booleanIs the text fixed or not
fontName?stringPostScript Font Name
fontSize?numberFont Size
lineHeight?numberLine Height of text
characterSpacing?numberSpacing between Characters
paragraphSpacing?numberSpacing between Paragraphs
horizontalAlignment?LayerHorizontalAlignmentHorizontal Alignment of a text
verticalAlignment?numberVertical Alignment of a text
color?LayerColorRefer to LayerColor
listStyle?LayerListStyleOne of "", disc or numbered
textTransform?LayerTextTransform0 for none, 1 is for uppercase and 2 is for lowercase
textDecoration?LayerTextDecorationRefer to LayerTextDecoration

LayerTextDecoration

PropertyTypeDescription
lineLayerTextDecorationLineRefer to LayerTextDecorationLine
styleLayerTextDecorationStyleRefer to LayerTextDecorationStyle

LayerTextDecorationLine

Value
underline
strikethrough

LayerTextDecorationStyle

Value
solid
double

LayerColor

PropertyTypeDescription
hex8stringColor in HEX8 (e.g. #RRGGBBAA)
rgbastringrgba of color (e.g. rgba(0, 0, 0, 0))
components.rednumberValue of red (0 to 1)
components.greennumberValue of green (0 to 1)
components.bluenumberValue of blue (0 to 1)
components.alphanumberAlpha of color (0 to 1)

LayerBlendMode

Can be one of these blend modes:

NameValueDescription
LayerBlendModeNormal0Normal
LayerBlendModeDarken1Darken
LayerBlendModeMultiply2Multiply
LayerBlendModeColorBurn3Color burn
LayerBlendModeLighten4Lighten
LayerBlendModeScreen5Screen
LayerBlendModeAdd6Add
LayerBlendModeOverlay7Overlay
LayerBlendModeSoftLight8Soft light
LayerBlendModeHardLight9Hard light
LayerBlendModeDifference10Difference
LayerBlendModeExclusion11Exclusion
LayerBlendModeHue12Hue
LayerBlendModeSaturation13Saturation
LayerBlendModeColor14Color
LayerBlendModeLuminosity15Luminosity

LayerBorderRadius

PropertyType
topLeftnumber
topRightnumber
bottomRightnumber
bottomLeftnumber

LayerFill

Can be either of these fill types:

  • LayerFillSolid
  • LayerFillGradient
  • LayerFillPattern
  • LayerFillNoise

LayerFillSolid

PropertyValueDescription
fillTypenumberValue: 0
blendModeLayerBlendModeRefer to LayerBlendMode
opacitynumber0 to 100 opacity level
colorLayerColorRefer to LayerColor

LayerFillGradient

PropertyValueDescription
fillTypenumberValue: 1
blendModeLayerBlendModeRefer to LayerBlendMode
opacitynumber0 to 100 opacity level of filling gradient
gradientLayerGradientRefer to LayerGradient

LayerFillPattern

PropertyValueDescription
fillTypenumbervalue: 4
blendModeLayerBlendModeRefer to LayerBlendMode
opacitynumber0 to 100 opacity level of filling pattern
patternFillTypenumberRefer to LayerFillPatternType
patternTileScalenumberScale value of fill
patternWidth?numberWidth of a pattern
patternHeight?numberHeight of a pattern
imageUrlstringImage url of a fill
imageIdstringImage id of a fill

LayerFillPatternType

ValueDescription
0Tile
1Fill
2Stretch
3Fit

LayerFillNoise

PropertyValueDescription
fillTypeLayerFillTypeNoiseValue: 5
blendModeLayerBlendModeRefer to LayerBlendMode
opacitynumber0 to 100 opacity level of filling noise
noiseIndexnumberOne of 1 (black), 2 (white), 3 (color)
noiseIntensitynumber0 to 100 intensity level of filling noise

LayerBorder

Can be either one of these border types:

  • LayerBorderSolid
  • LayerBorderGradient

LayerBorderSolid

PropertyValueDescription
fillTypeLayerFillTypeSolidValue: 0
positionLayerBorderPositionRefer to LayerBorderPosition
thicknessnumberSize of the border stroke
colorLayerColorRefer to LayerColor

LayerBorderGradient

PropertyValueDescription
fillTypeLayerFillTypeGradientValue: 1
positionLayerBorderPositionRefer to LayerBorderPosition
thicknessnumberSize of the border stroke
colorLayerGradientRefer to LayerGradient

LayerBorderPosition

ValueDescription
0Center
1Inside
2Outside

LayerGradient

PropertyValueDescription
gradientTypenumberValue: 0 for linear, 1, for radial, 2 for angular
from[number, number]Coords from where to start a gradient
to[number, number]Coords from where to end a gradient
stopsLayerGradientStop[]List of colors stops for the gradient
ellipseLengthnumberLength of a gradient ellipse

LayerGradientStop

PropertyValueDescription
positionnumberAt which position value the gradient want to be changed
colorLayerColorWhat color will it get changed to

LayerShadows

PropertyValueDescription
outer?LayerShadow[]Shadow outside of layer
inner?LayerShadow[]Shadow inside of layer

LayerShadow

PropertyValueDescription
colorLayerColorColoring of a shadow
blurRadiusnumberRadius of blur
spreadnumberSpread value of a shadow
xnumberHorizontal coords of a shadow
ynumberVertical coords of a shadow

LayerResizingConstraint

PropertyValue
top?boolean
right?boolean
bottom?boolean
left?boolean
fixedWidth?boolean
fixedHeight?boolean

LayerOverrideData

PropertyValueDescription
symbolId?booleanThe id of a symbol that gets overwritten
properties?LayerOverridePropertiesProperties that the layer will overwrite
[layerId: string]string/Object/LayerOverrideDataAn id of a layer that will be overwritten

LayerOverrideProperties

  type LayerOverrideProperties = {
    ...$Diff<LayerDataProperties, { overrides: * }>
  };

LayerDataAsset

PropertyValueDescription
fileFormatstringFormat of a file
formatNamestringName of format of an asset
namingSchemestringNaming scheme for an asset
scalestringScale of an asset

Retrieve layer data

CLI API

data.info(LayerVersionDescriptor, RequestOptions): Promise<LayerDataset>

abstract.data.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a" // or sha: "latest"
});

Files

A file represents a standard file – in Abstract a file is always loaded from a specific commit SHA, or point in time.

The file object

PropertyTypeDescription
applicationDocumentVersionnumberThe application (eg Sketch's) version of the file
applicationVersionstringThe version of the application the file was created with
idstringUUID identifier for the file
isLibrarybooleanIs this file a library file or not
lastChangedAtShastringSHA that represents the commit where this file was last changed
namestringThe name of the file
projectIdstringUUID of the project this file belongs to
shastringSHA that this file was loaded at
typestringThe application that the file was created in
updatedAtstringThe timestamp of the last change to the file

List all files

CLI API

files.list(BranchDescriptor, RequestOptions): Promise<File[]>

List the files for a branch at the latest commit

abstract.files.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  sha: "latest"
});

Retrieve a file

CLI API

files.info(FileDescriptor, RequestOptions): Promise<File>

Load the file info for the latest commit on a branch

abstract.files.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7"
  sha: "latest"
});

Export a file

CLI API

files.raw(FileDescriptor, RawProgressOptions): Promise<ArrayBuffer | void>

Retrieve a Sketch file from Abstract based on its file ID and save it to disk. Files will be saved to the current working directory by default, but a custom filename option can be used to customize this location.

abstract.files.raw({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7"
  sha: "latest"
});

The resulting ArrayBuffer can be also be used with node fs APIs directly. For example, it's possible to write the file to disk manually after post-processing it:

const fs = require("fs");
const arrayBuffer = await abstract.files.raw({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7"
  sha: "latest"
}, {
  disableWrite: true
});

fs.writeFile("file.sketch", Buffer.from(arrayBuffer), (err) => {
  if (err) throw err;
  console.log("File written!");
});

It's also possible to get insight into the underlying progress of the file export.

abstract.files.raw({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7"
  sha: "latest"
}, {
  onProgress: (receivedBytes: number, totalBytes: number) => {
    console.log(`${receivedBytes * 100 / totalBytes}% complete`);
  }
});

Layers

A layer is a container for designs. In Sketch a layer usually represents an artboard however it can also be a non-contained layer floating on the page.

The layer object

PropertyTypeDescription
fileIdstringUUID of the file that this layer is contained within
heightnumberThe height of the layer in pixels
idstringUUID identifier of the layer
lastChangedAtShastringSHA of the commit where the layer was last changed
libraryIdstringUUID of the library file that this layer was included from
namestringThe name of the layer
ordernumberThe order of the layer in the page
pageIdstringUUID of the page that this layer is contained within
projectIdstringUUID of the project that this layer is contained within
shastringSHA of the commit this layer was loaded at
typestringThe type of the layer, eg "artboard"
updatedAtstringTimestamp of the commit that this layer was last changed
widthnumberThe width of the layer in pixels
xnumberThe horizontal position of the layer on the page, measured from the left
ynumberThe vertical position of the layer on the page, measured from the top

List all layers

CLI API

layers.list(FileDescriptor | PageDescriptor, LayersListOptions): Promise<Layer[]>

List the layers for a file at a commit

abstract.layers.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  sha: "fb7e9b50da6c330fc43ffb369616f0cd1fa92cc2"
});

As a file can contain a lot of layers we recommend filtering by page and adding a limit…

abstract.layers.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  pageId: "7D2D2599-9B3F-49BC-9F86-9D9D532F143A",
  sha: "fb7e9b50da6c330fc43ffb369616f0cd1fa92cc2"
}, {
  limit: 25,
  offset: 0
});

A file can also contain layers from external libraries. If you'd like to only see the layers in this file and not the external library elements they depend upon, use the fromLibraries option…

abstract.layers.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  pageId: "7D2D2599-9B3F-49BC-9F86-9D9D532F143A",
  sha: "fb7e9b50da6c330fc43ffb369616f0cd1fa92cc2"
}, {
  limit: 25,
  offset: 0,
  fromLibraries: "exclude"
});

Retrieve a layer

CLI API

layers.info(LayerVersionDescriptor, RequestOptions): Promise<Layer>

Load the info for a layer in a file at the latest commit on a branch

abstract.layers.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "latest"
});

Memberships

A membership contains information about a user's role within an organization or a project. A membership is created when a user joins an organization or is given access to a project.

The membership object

PropertyTypeDescription
createdAtstringTimestamp indicating when this membership was created
organizationIdstringUUID of the organization this membership belongs to
projectIdstringUUID of the project this membership belongs to
rolestringType of this membership
userIdstringUUID of the user that this membership represents
userUserThe user that this membership represents

List all memberships

API

memberships.list(OrganizationDescriptor | ProjectDescriptor, RequestOptions): Promise<Membership[]>

List the members of an organization

abstract.memberships.list({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Retrieve a membership

API

memberships.info(OrganizationMembershipDescriptor | ProjectMembershipDescriptor, RequestOptions): Promise<Membership>

Load the info for a specific member

abstract.memberships.info({
  userId: "48b5d670-2002-45ea-929d-4b00863778e4",
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Notifications

A notification is a user-facing message triggered by an underlying activity. Notifications are both viewable and dismissable in the desktop application.

The notification object

PropertyTypeDescription
branchIdstringUUID of the branch that triggered this notification, if applicable
commentIdstringUUID of the comment that triggered this notification, if applicable
createdAtstringTimestamp at which the notification was sent
idstringUUID identifier of the notification
initiatingUserUserUser that triggered this notification, if applicable
initiatingUserIdstringUUID of the user that triggered this notification, if applicable
messageTypestringThe type of this activity that triggered this notification, may be one of BRANCH_ARCHIVED, BRANCH_CREATED, BRANCH_DELETED, BRANCH_DESCRIPTION_UPDATED, BRANCH_RENAMED, BRANCH_STATUS_UPDATED, BRANCH_UNARCHIVED, COLLECTION_PUBLISHED, COMMENT_CREATED, COMMIT, MERGE_COMMIT, PROJECT_ARCHIVED, PROJECT_CREATED, PROJECT_DELETED, PROJECT_DESCRIPTION_CHANGED, PROJECT_RENAMED, PROJECT_TRANSFERRED, PROJECT_UNARCHIVED, REVIEWER_REMOVED, REVIEW_COMPLETED, REVIEW_DISMISSED, REVIEW_REQUESTED, UPDATE_COMMIT
organizationstringOrganization that triggered this notification, if applicable
organizationIdstringUUID of the organization that triggered this notification, if applicable
projectstringProject that triggered this notification, if applicable
projectIdstringUUID of the project that triggered this notification, if applicable
payloadObjectObject containing information specific to activity that triggered this notification
readAtstringTimestamp at which the notification was read or dismissed

List notifications

API

notifications.list(OrganizationDescriptor, ListOptions): CursorPromise<Notification[]>

List the first two notifications for a given organization

abstract.notifications.list({
  organizationId: "8a13eb62-a42f-435f-b3a3-39af939ad31b"
}, { limit: 2 });

Note: This endpoint returns a special type of Promise called a CursorPromise that supports cursor-based pagination. More information can be found here.

Retrieve a notification

API

notifications.info(NotificationDescriptor, RequestOptions): Promise<Notification>

Load the info for a notification

abstract.notifications.info({
  notificationId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Organizations

Organizations contain users and projects.

The organization object

PropertyTypeDescription
hasBillingInfobooleanWhether this organization has billing information on file
idstringUUID
isUsernameOrganizationbooleanA username organization is a free organization included with every user account
isWithinSubscriptionTermbooleanWhether the organizations subscription is in good standing
logoUrlstringA url for the organization logo
namestringThe name of the organization
privateProjectPublicSharingEnabledbooleanFlag indicating if this organization has sharing of private projects enabled
publicSharingEnabledbooleanFlag indicating if this organization has sharing of public projects enabled
restrictedToDomainsstring[]An optional list of domain names that invitations to this organization are restricted to
trialEndsAtstringTimestamp of when the trial ends, if within trial period
userIdstringUUID of the user that created the organization

List all organizations

API

organizations.list(RequestOptions): Promise<Organization[]>

Load the organizations accessible by the current access token

abstract.organizations.list();

Retrieve an organization

API

organizations.info(OrganizationDescriptor, RequestOptions): Promise<Organization>

Load the info for an organization

abstract.organizations.info({
  organizationId: "8a13eb62-a42f-435f-b3a3-39af939ad31b"
});

Pages

A page is a container for layers, often a file will have several pages to organize design work.

The page object

PropertyTypeDescription
fileIdstringUUID of the file that this page is contained within
idstringUUID identifier for the page
namestringThe name of the page
ordernumberThe order of the page in the file
projectIdstringUUID of the project this page belongs to
shastringSHA of the commit this page was loaded at
typestringThis field has the value "library" for virtual library pages

List all pages

CLI API

pages.list(FileDescriptor, RequestOptions): Promise<Page[]>

List the pages for a file at a commit

abstract.pages.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  sha: "fb7e9b50da6c330fc43ffb369616f0cd1fa92cc2"
});

Retrieve a page

CLI API

pages.info(PageDescriptor, RequestOptions): Promise<Page>

Load the info for a page in a file at the latest commit on a branch

abstract.pages.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  pageId: "7D2D2599-9B3F-49BC-9F86-9D9D532F143A"
});

Previews

A preview is an image file that represents the rendered version of a layer. In Abstract all previews are currently only available in PNG format.

The preview object

PropertyTypeDescription
webUrlstringA url to where this preview can be loaded in the Abstract web app

Retrieve an image file

API

previews.raw(LayerVersionDescriptor, RawOptions): Promise<ArrayBuffer>

Retrieve a preview image for a layer at a specific commit and save it to disk. Files will be saved to the current working directory by default, but a custom filename option can be used to customize this location.

const arrayBuffer = await abstract.previews.raw({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a" // or sha: "latest"
});

The resulting ArrayBuffer can be also be used with node fs APIs directly. For example, it's possible to write the file to disk manually after post-processing it:

const arrayBuffer = await abstract.previews.raw({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  pageId: "7D2D2599-9B3F-49BC-9F86-9D9D532F143A",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a" // or sha: "latest"
}, {
  disableWrite: true
});

processedBuffer = postProcess(arrayBuffer);

fs.writeFile(`preview.png`, Buffer.from(processedBuffer), (err) => {
  if (err) throw err;
  console.log("Preview image written!");
});

Retrieve a preview image url

API

Note: The previews.url method requires an environment with URL.createObjectURL. If you are using node, you will need to save the image to a file with previews.raw

previews.url(LayerVersionDescriptor, RequestOptions): Promise<string>

Get an image as a temporary blob url which can be displayed directly in an image tag or downloaded. The url exists only as long as the current browser session and should not be saved to a database directly.

abstract.previews.url({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a" // or sha: "latest"
});

Retrieve a preview

API

previews.info(LayerVersionDescriptor, RequestOptions): Promise<Preview>

Load the info for a layer preview

abstract.previews.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a" // or sha: "latest"
});

Projects

A project is a container for files, it belongs to an organization. Teams use projects to logically separate their files for example for a project, a platform (e.g. Web / iOS), or by client.

The project object

PropertyTypeDescription
aboutstringA longer description of the project (May optionally include markdown tags)
archivedAtstringTimestamp that the project was archived
assetAutoGenerationstringStatus of project asset generation. One of "all", "master", or "off".
colorstringA hex value that represents a custom project color
createdAtstringTimestamp that the project was created
createdByUserUserThe user that created the project
firstPushedAtstringTimestamp that the project first received data
idstringUUID
isNewbooleanTrue if nobody has committed in this project yet
namestringThe name of the project
organizationIdstringUUID of the organization this project belongs to
pushedAtstringTimestamp that data was last received
repoCreatedAtstringTimestamp that the backend storage was created
sizeInBytesnumberThe size of the project on disk in bytes
updatedAtstringTimestamp that the project was last updated
visibilitystringEither "organization" for a team project, or "specific" for a private project

NewProject

PropertyTypeDescription
aboutstringA longer description of the project (May optionally include markdown tags)
assetAutoGenerationstringStatus of project asset generation. One of "all", "master", or "off".
colorstringA hex value that represents a custom project color
createdAtstringTimestamp that the project was created
namestringThe name of the project
organizationIdstringUUID of the organization this project belongs to
sectionIdstringUUID of the section this project belongs to
visibilitystringEither "organization" for a team project, or "specific" for a private project

List all projects

API

projects.list(OrganizationDescriptor?, { ...RequestOptions, filter?: "active" | "archived", sectionId?: string }): Promise<Project[]>

List all projects accessible through the current authentication

abstract.projects.list();

or, get a list of projects for a specific organization…

abstract.projects.list({
  organizationId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

or, get a list of active projects for a specific organization…

abstract.projects.list({
  organizationId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
}, { filter: "active" });

or, get a list of active projects for a specific section within an organization…

abstract.projects.list({
  organizationId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  sectionId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
}, { filter: "active" });

Retrieve a project

API

projects.info(ProjectDescriptor, RequestOptions): Promise<Project>

Load the info for a project

abstract.projects.info({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Create a project

API

projects.create(OrganizationDescriptor, NewProject, RequestOptions): Promise<Project>

Create a new project

abstract.projects.create({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
}, {
  name: "New Project",
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Delete a project

API

projects.delete(ProjectDescriptor, RequestOptions): Promise<void>

Delete a project

abstract.projects.delete({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Update a project

API

projects.update(ProjectDescriptor, Project, RequestOptions): Promise<Project>

Update an existing project

abstract.projects.update({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
}, {
  ...existingProject,
  name: "Updated Project Name"
});

Archive a project

API

projects.archive(ProjectDescriptor, RequestOptions): Promise<Project>

Archive a project

abstract.projects.achive({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Un-archive a project

API

projects.unarchive(ProjectDescriptor, RequestOptions): Promise<Project>

Un-archive a project

abstract.projects.unarchive({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Review Requests

A review request represents a notification to review a given branch of work.

The review request object

PropertyTypeDescription
branchIdstringThe ID of the branch being reviewed
commentIdstringID of the comment associated with this review request
createdAtstringTimestamp indicating when this review was requested
idstringUUID of this review request
projectIdstringID of the project that the reviewed branch belongs to
requesterUserUser who initiated or created this review request
reviewerUserUser who was requested to review this work
requesterIDUserID of the user who initiated or created this review request
reviewerIDUserID of the user who was requested to review this work
statusstringStatus of this review, one of APPROVED or REJECTED
statusChangedAtstringTimestamp indicating when this review was last updated

List all review requests

API

reviewRequests.list(OrganizationDescriptor | ProjectDescriptor | BranchDescriptor, RequestOptions): Promise<ReviewRequest[]>

List all review requests for a given branch

abstract.reviewRequests.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master"
});

List all review requests for a given project, regardless of branch

abstract.reviewRequests.list({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

List all review requests for a given organization, regardless of project

abstract.reviewRequests.list({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Sections

A section is a group of projects that belong to a given organization. Sections are used to group similar or related projects together and can be created using the desktop application.

The section object

PropertyTypeDescription
idstringUUID
namestringThe name of the section
organizationIdstringUUID of the organization this section belongs to

List all sections

API

sections.list(OrganizationDescriptor, RequestOptions): Promise<Section[]>

List all sections accessible through the current authentication

abstract.sections.list({ organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9" });

Shares

A share is a shareable url to an object in Abstract. You can use the desktop or web app to create a share url.

Note: The format of a share url is https://share.goabstract.com/<UUID>.

The share object

PropertyTypeDescription
descriptorDescriptorA descriptor for the shared object
appUrlstringA url that can be used to open the desktop app
userIdstringUUID of the user that created the share
idstringUUID

Note: The descriptor property can be used as the first argument for many of the SDK methods

Load info for a share

API

shares.info(ShareDescriptor | ShareUrlDescriptor, RequestOptions): Promise<Share>

abstract.shares.info({
  url: 'https://share.goabstract.com/49b1f582-a8b4-46ca-8c86-bbc675fe27c4'
});

or, by id…

abstract.shares.info({
  shareId: '49b1f582-a8b4-46ca-8c86-bbc675fe27c4'
});

Using share.descriptor

API

shares.info(ShareDescriptor | ShareUrlDescriptor, RequestOptions): Promise<Share>

List all files for branch's share url

const branchShare = await abstract.shares.info({
  url: 'https://share.goabstract.com/49b1f582-a8b4-46ca-8c86-bbc675fe27c4'
})

const branchFiles = await abstract.files.list(branchShare.descriptor);

Create a share

API

shares.create(OrganizationDescriptor, InputShare, RequestOptions): Promise<Share>

Create a layer share in your organization

abstract.shares.create({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
}, {
  kind: "layer",
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78",
  branchId: "master",
  fileId: "51DE7CD1-ECDC-473C-B30E-62AE913743B7",
  pageId: "7D2D2599-9B3F-49BC-9F86-9D9D532F143A",
  layerId: "CA420E64-08D0-4B96-B0F7-75AA316B6A19",
  sha: "c4e5578c590f5334349b6d7f0dfd4d3882361f1a" // or sha: "latest"
});

Stars

A star represents an underlying project or section of projects, and it indicates that a user has favorites the underlying object for easier discovery.

The star object

PropertyTypeDescription
starrableIdstringThe ID of the underlying project or section that this star represents
starrableTypestringIndicates the type of the underlying entity, either "Project" or "Section"
starredAtstringTimestamp that the project or section was starred

List all starred projects or sections

API

stars.list(RequestOptions): Promise<Star[]>

List all starred projects or sections

abstract.stars.list();

Star a project

API

stars.create(ProjectDescriptor | SectionDescriptor, RequestOptions): Promise<Star>

Star a project

abstract.stars.create({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Un-star a project

API

stars.delete(ProjectDescriptor | SectionDescriptor, RequestOptions): Promise<void>

Un-star a project

abstract.stars.delete({
  projectId: "616daa90-1736-11e8-b8b0-8d1fec7aef78"
});

Users

A user contains information specific to an individual account. Users are global to Abstract and are not specific to organizations. A user is created in the application by creating a new account.

The user object

PropertyTypeDescription
avatarUrlstringURL of the avatar for this user
createdAtstringTimestamp indicating when this account was created
deletedAtstringTimestamp indicating when this account was deleted
idstringUUID identifier for the user
namestringThe name of the page
primaryEmailIdstringID of the primary email for this user
updatedAtstringTimestamp indicating when this account was updated
usernamestringUsername associated with this user

List all users

API

users.list(OrganizationDescriptor | ProjectDescriptor, RequestOptions): Promise<User[]>

List the users in an organization

abstract.users.list({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Retrieve a user

API

users.info(UserDescriptor, RequestOptions): Promise<User>

Load the info for a specific user

abstract.users.info({
  userId: "48b5d670-2002-45ea-929d-4b00863778e4"
});

Webhooks

Webhooks make it easy to efficiently subscribe to events across the Abstract platform. Webhooks live at the organization level, and organization administrators can create new webhooks within an organization's settings in the web application.

Note: Additional information on webhooks can be found here.

The webhook object

PropertyTypeDescription
activebooleanIndicates if this webhook is currently listening for new events
createdAtstringTimstamp indicating when this webhook was created
errorCountnumberNumber indicating the number of failed deliveries for this webhook
eventsWebhookEvent[]Array of webhook event objects configured for this webhook
idstringUUID identifier for this webhook
lastPushedAtstringTimstamp indicating the time of the most recent delivery for this webhook
organizationIdstringUUID of the organization this webook belongs to
updatedAtstringTimstamp indicating when this webhook was last updated
urlstringURL that this webhook will POST deliveries to
userUserThe user that created the webhook

WebhookEvent

PropertyTypeDescription
idstringUUID identifier for this webhook event
groupWebhookGroupCategory that this webhook event belongs to
namestringThe name of this webhook event

WebhookGroup

PropertyTypeDescription
idstringUUID identifier for this webhook event group
namestringThe name of this webhook event group

NewWebhook

PropertyTypeDescription
activebooleanIndicates if this webhook is currently listening for new events
eventsWebhookEvent[]Array of webhook event objects configured for this webhook
keystringAn optional secret used to validate deliveries for this webhook
organizationIdstringUUID of the organization this webook belongs to
urlstringURL that this webhook will POST deliveries to

List an organization's webhooks

API

webhooks.list(OrganizationDescriptor, RequestOptions): Promise<Webhook[]>

List all webhooks for a given organization

abstract.webhooks.list({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Retrieve a webhook

API

webhooks.info(WebhookDescriptor, RequestOptions): Promise<Webhook>

Retrieve a single webhook

abstract.webhooks.info({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9",
  webhookId: "03df2308-82a7-4a05-b9e9-c31ad569249d"
});

List available webhook events

API

webhooks.events(OrganizationDescriptor, RequestOptions): Promise<WebhookEvent[]>

List all available webhook events

abstract.webhooks.events({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
});

Create a webhook

API

webhooks.create(OrganizationDescriptor, NewWebhook, RequestOptions): Promise<Webhook>

Create a new webhook

abstract.webhooks.create({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
}, {
  active: true,
  events: [ 'project.created' ],
  organizationId: "4ed01dff-4bc7-47cd-8b51-9ea3ec9e5de4",
  url: "https://example-url.com/postreceive"
});

Update a webhook

API

webhooks.update(OrganizationDescriptor, Webhook, RequestOptions): Promise<Webhook>

Update an existing webhook

abstract.webhooks.update({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9"
}, {
  active: false,
  events: [ 'project.updated' ],
  organizationId: "4ed01dff-4bc7-47cd-8b51-9ea3ec9e5de4",
  url: "https://another-example-url.com/postreceive"
});

Delete a webhook

API

webhooks.delete(WebhookDescriptor, RequestOptions): Promise<void>

Delete a webhook

abstract.webhooks.delete({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9",
  webhookId: "03df2308-82a7-4a05-b9e9-c31ad569249d"
});

Send a test event to a webhook

API

webhooks.ping(WebhookDescriptor, RequestOptions): Promise<void>

Send a test event to an existing webhook

abstract.webhooks.ping({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9",
  webhookId: "03df2308-82a7-4a05-b9e9-c31ad569249d"
});

List all deliveries for a webhook

API

webhooks.deliveries(WebhookDescriptor, RequestOptions): Promise<WebhookDelivery[]>

List all deliveries for a webhook

abstract.webhooks.deliveries({
  organizationId: "d147fba5-c713-4fb9-ab16-e7e82ed9cbc9",
  webhookId: "03df2308-82a7-4a05-b9e9-c31ad569249d"
});

Verify a webhook delivery

API

webhooks.verify(WebhookDelivery, expectedSignature, signingKey, RequestOptions): Promise<boolean>

Verify that a webhook delivery payload was sent by Abstract

app.post("/webhook", async (req, res) => {
  const payload = req.body;
  const expectedSignature = req.header("Abstract-Webhooks-Signature");
  const signingKey = process.env.WEBHOOK_SIGNING_KEY;

  const verified = await abstract.webhooks.verify(payload, expectedSignature, signingKey);

  // Webhook verified, do something with payload data...
});

Note: This endpoint is intended to be used on a webhook server to verify that incoming delivery requests were sent by Abstract. More information on webhook security techniques can be found here.

Request options

Options objects that can be passed to different SDK endpoints.

RequestOptions

{
  transportMode?: ("api" | "cli")[]
}

ListOptions

{
  transportMode?: ("api" | "cli")[],
  limit?: number,
  offset?: number
}

LayersListOptions

{
  transportMode?: ("api" | "cli")[],
  limit?: number,
  offset?: number
  fromLibraries?: "include" | "exclude" | "only" # default is "include"
}

RawOptions

{
  transportMode?: ("api" | "cli")[],
  disableWrite?: boolean,
  filename?: string
}

RawProgressOptions

{
  transportMode?: ("api" | "cli")[],
  disableWrite?: boolean,
  filename?: string,
  onProgress?: (receivedBytes: number, totalBytes: number) => void;
}

CollectionsListOptions

{
  branchStatus?: string,
  layersPerCollection?: number | "all",
  limit?: number,
  offset?: number,
  search?: string,
  sortBy?: string,
  sortDir?: string,
  transportMode?: ("api" | "cli")[],
  userId?: string
}

Descriptors

Reference for the parameters required to load resources with the Abstract SDK.

OrganizationDescriptor

{ organizationId: string }

ProjectDescriptor

{ projectId: string }

ShareDescriptor

{ shareId: string }

ShareUrlDescriptor

{ url: string }

BranchDescriptor

{
  projectId: string,
  branchId: string | "master"
}

BranchCommitDescriptor

{
  projectId: string,
  branchId: string | "master",
  sha: string
}

CommitDescriptor

{
  projectId: string,
  sha: string
}

FileDescriptor

{
  projectId: string,
  branchId: string | "master",
  fileId: string,
  sha: string | "latest"
}

PageDescriptor

{
  projectId: string,
  branchId: string | "master",
  fileId: string,
  pageId: string,
  sha: string
}

LayerDescriptor

{
  projectId: string,
  branchId: string | "master",
  fileId: string,
  layerId: string
}

LayerVersionDescriptor

{
  projectId: string,
  branchId: string | "master",
  fileId: string,
  layerId: string,
  sha: string | "latest"
}

CollectionDescriptor

{
  projectId: string,
  branchId: string | "master",
  collectionId: string
}

ActivityDescriptor

{ activityId: string }

NotificationDescriptor

{ notificationId: string }

CommentDescriptor

{ commentId: string }

UserDescriptor

{ userId: string }

AssetDescriptor

{
  assetId: string,
  projectId: string
}

ProjectMembershipDescriptor

{
  projectId: string,
  userId: string
}

OrganizationMembershipDescriptor

{
  organizationId: string,
  userId: string
}

WebhookDescriptor

{
  organizationId: string,
  webhookId: string
}

WebhookDeliveryDescriptor

{
  deliveryId: string,
  organizationId: string,
  webhookId: string
}
← EmbedsSketch →
  • Activities
    • The activity object
    • List all activities
    • Retrieve an activity
  • Assets
    • The asset object
    • Retrieve an asset
    • List assets for a file
    • List assets for a commit
    • Export an asset file
    • Example: Save all assets for a given file
  • Branches
    • The branch object
    • List all branches
    • Retrieve a branch
  • BranchMergeState
    • The branch merge state object
    • Merge state of a branch
    • Update a branch
  • Changesets
    • The Changeset object
    • Retrieve a changeset for a commit
    • Retrieve a changeset for a branch
  • Collections
    • List all collections
    • Retrieve a collection
    • Create a collection
    • Update a collection
  • CollectionLayers
    • The CollectionLayer object
    • Add a single layer to a collection
    • Add multiple layers to a collection
    • Remove a layer from a collection
    • Update a layer within a collection
    • Reorder a layer within a collection
  • Comments
    • The comment object
    • List all comments
    • Retrieve a comment
    • Create a comment
  • Commits
    • The commit object
    • List all commits
    • Retrieve a commit
  • Data
    • The LayerDataset object
    • LayerData
    • LayerDataProperties
    • LayerTextStyle
    • LayerTextDecoration
    • LayerTextDecorationLine
    • LayerTextDecorationStyle
    • LayerColor
    • LayerBlendMode
    • LayerBorderRadius
    • LayerFill
    • LayerFillSolid
    • LayerFillGradient
    • LayerFillPattern
    • LayerFillPatternType
    • LayerFillNoise
    • LayerBorder
    • LayerBorderSolid
    • LayerBorderGradient
    • LayerBorderPosition
    • LayerGradient
    • LayerGradientStop
    • LayerShadows
    • LayerShadow
    • LayerResizingConstraint
    • LayerOverrideData
    • LayerOverrideProperties
    • LayerDataAsset
    • Retrieve layer data
  • Files
    • The file object
    • List all files
    • Retrieve a file
    • Export a file
  • Layers
    • The layer object
    • List all layers
    • Retrieve a layer
  • Memberships
    • The membership object
    • List all memberships
    • Retrieve a membership
  • Notifications
    • The notification object
    • List notifications
    • Retrieve a notification
  • Organizations
    • The organization object
    • List all organizations
    • Retrieve an organization
  • Pages
    • The page object
    • List all pages
    • Retrieve a page
  • Previews
    • The preview object
    • Retrieve an image file
    • Retrieve a preview image url
    • Retrieve a preview
  • Projects
    • The project object
    • List all projects
    • Retrieve a project
    • Create a project
    • Delete a project
    • Update a project
    • Archive a project
    • Un-archive a project
  • Review Requests
    • The review request object
    • List all review requests
  • Sections
    • The section object
    • List all sections
  • Shares
    • The share object
    • Load info for a share
    • Using share.descriptor
    • Create a share
  • Stars
    • The star object
    • List all starred projects or sections
    • Star a project
    • Un-star a project
  • Users
    • The user object
    • List all users
    • Retrieve a user
  • Webhooks
    • The webhook object
    • List an organization's webhooks
    • Retrieve a webhook
    • List available webhook events
    • Create a webhook
    • Update a webhook
    • Delete a webhook
    • Send a test event to a webhook
    • List all deliveries for a webhook
    • Verify a webhook delivery
  • Request options
    • RequestOptions
    • ListOptions
    • LayersListOptions
    • RawOptions
    • RawProgressOptions
    • CollectionsListOptions
  • Descriptors
    • OrganizationDescriptor
    • ProjectDescriptor
    • ShareDescriptor
    • ShareUrlDescriptor
    • BranchDescriptor
    • BranchCommitDescriptor
    • CommitDescriptor
    • FileDescriptor
    • PageDescriptor
    • LayerDescriptor
    • LayerVersionDescriptor
    • CollectionDescriptor
    • ActivityDescriptor
    • NotificationDescriptor
    • CommentDescriptor
    • UserDescriptor
    • AssetDescriptor
    • ProjectMembershipDescriptor
    • OrganizationMembershipDescriptor
    • WebhookDescriptor
    • WebhookDeliveryDescriptor
Copyright © 2025 Abstract Studio Design, Inc.