REST API

Introduction

The Specify API is based on REST structure. We support authentication via access tokens. Requests are made via HTTP endpoints with clear functions and appropriate response codes. Endpoints allow you to request design tokens and assets from a Specify repository.

What you can do with the REST API

Specify's REST API is useful if you want to use design data coming from Specify through custom scripts like a Figma plugin or a Raycast script.

In short, our REST API helps you request design data through HTTP requests. Like with our CLI you can use parsers to transform design data.

However, you cannot directly generate files using the REST API as it only returns text. You'll have to write custom scripts to generate design files (e.g., colors.css).

To sum things up, to generate files from Specify (e.g., colors.css or icon.svg) containing design tokens or assets use the CLI or our GitHub application.

Endpoint

Specify provides the following endpoint to help you get design tokens and assets from a Specify repository.

https://api.specifyapp.com/repository/{workspace}/{repository}/design-tokens

Parameters

POST https://api.specifyapp.com/repository/{workspace}/{repository}/design-tokens

Get design tokens and assets from a Specify repository.

Path Parameters

Request Body

{
    // Response
}

{
    // Response
}

{
    // Response
}

{
    // Response
}

{
    // Response
}

Once you have your personal access token, you can pass it within the Authorization header of your request.

Example

Here's a simple example to get colors in CSS variables from a repository called all-design-datain the @acme-inc workspace:

curl -X POST 'https://api.specifyapp.com/repository/@acme-inc/all-design-data/design-tokens' \
  -H 'Authorization: <your-personal-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"filter": { "types": ["color"]}, "parsers": [{"name": "to-css-custom-properties"}]}'

Errors

Specify uses standard HTTP response codes for success and failure notifications. Our errors are further classified by type. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Specify servers.

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

Attributes