# 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

<figure><img src="https://2627198405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9mLpgMKJql1OpDNVdcbF%2Fuploads%2Fgit-blob-61dda55d520121d6d15166ab83ae3f0004de9237%2Fspecify-api.jpg?alt=media" alt=""><figcaption><p>Overview of the possibilities offered by the Specify API</p></figcaption></figure>

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](https://www.raycast.com/).

In short, our REST API helps you request design data through HTTP requests. Like with our [CLI](https://docs.specifyapp.com/v1/apps-and-tools/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](https://docs.specifyapp.com/v1/apps-and-tools/cli) or our [GitHub application](https://docs.specifyapp.com/v1/apps-and-tools/github).

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

<mark style="color:green;">`POST`</mark> `https://api.specifyapp.com/repository/{workspace}/{repository}/design-tokens`

Get design tokens and assets from a Specify repository.

#### Path Parameters

| Name                                        | Type   | Description                                                                                                                                                                                                      |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace<mark style="color:red;">\*</mark> | String | <p>The name of your organization in Specify.</p><p>For instance, in this URL <code><https://specifyapp.com/@specifyapp/Seeds/color></code> the workspace is "@specifyapp".</p>                                   |
| name<mark style="color:red;">\*</mark>      | String | <p>The name of the Specify repository containing the design data you're requesting.</p><p>For instance, in this URL <code><https://specifyapp.com/@specifyapp/Seeds/color></code> the repository is "Seeds".</p> |

#### Request Body

| Name    | Type            | Description                                                                                                                                                                 |
| ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter  | Object          | <p>Set all the <a href="../concepts/token-types">Token types</a> you want to target.</p><p></p><p><code>"filter": { "types": \[ "color", "font", "textStyle" ] }</code></p> |
| parsers | Object or Array | Can contain an object or an array of objects. Each object corresponds to a specific [parser](https://docs.specifyapp.com/v1/concepts/parsers#all-parsers-available).        |

{% tabs %}
{% tab title="200: OK Everything worked as expected." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized No valid API key provided." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden The API key doesn" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="404: Not Found The requested resource doesn" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on Specify" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

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-data`in the `@acme-inc` workspace:

```bash
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

<table><thead><tr><th width="175.33333333333331">Property</th><th width="113">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>string</code></td><td>The type of error returned. One of <code>api_connection_error</code>, <code>api_error</code>, <code>authentication_error</code>, <code>invalid_request_error</code>, or <code>rate_limit_error</code>.</td></tr><tr><td><code>statusCode</code></td><td><code>string</code></td><td>For some errors that could be handled programmatically, a short string indicating the error code reported.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>A human-readable message providing more details about the error.</td></tr><tr><td><code>validation</code></td><td><code>string</code></td><td>All invalid query / payload parameters. All invalid query / payload parameters. This property will be displayed on specific endpoints error response.</td></tr></tbody></table>