Introduction

Welcome to Specify, the world's first design API.

Specify helps you unify your brand identity by collecting, storing and distributing design tokens and assets — automatically. Specify's mission is to give organizations total control on their design decisions at scale.

We simplify the process of collecting design decisions, a.k.a design tokens and assets, and hooking up new tools, allowing you to spend more time using design and less time trying to collect it.

When you start out, you create a repository, which serves as a container for all of your sources and destinations. Sources send data into Specify, while destinations receive data from Specify.

What can I do with the Specify API?

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 specific repository.

Base URL

https://beta.api.specifyapp.com

Getting Started

To query the Specify API, you need a personal access token.

Generate one from:

Getting your first design tokens

Get your first design tokens by:

  1. Creating a repository
  2. Collecting your design tokens from a specific source
  3. Getting the owner and the reposity name. You can find them in the URL which resembles this: /{owner}/{repositoryName}
  4. Calling the route POST https://beta.api.specifyapp.com/{owner}/{repositoryName}/design-tokens

For further explanation, please consult the get design token endpoint.

Using the design tokens

You can pull your design tokens by:

  • Using the REST API with its parsers to pull design tokens
  • Using the Specify CLI. You can find more informations on the CLI documentation page

Try it yourself

What's this?

POST /repository/{owner}/{name}/design-tokens

curl -X POST 'https://beta.api.specifyapp.com/repository/{owner}/{name}/design-tokens' \
  -H 'Authorization: <personal access token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Authentication

Before accessing to an endpoint within Specify, you will need to provide a valid authentication.

The personal access token gives the holder access to the workspace through the API where design tokens are stored in repositories.

Get Design Tokens

HTTP Endpoint

POST /repository/{owner}/{name}/design-tokens

Parameters

  • owner string

    The name of the owner of repository containing the design tokens you're requesting.

  • name string

    The name of the repository containing the design tokens you're requesting.

  • body optional

    Child parameters

    • filter object optional

      An object containing all the filters your requested design tokens will go through. Currently, you can only filter your design tokens by their type. To know more see our example use case.

    • parsers array optional

      Can contain an object or an array of objects. Each object corresponds to a specific parser.

Errors

  • 400

    Error with the request. The "message" param on the response will describe the error.

To learn more, see all error attributes.

Try it yourself

What's this?

POST /repository/{owner}/{name}/design-tokens

curl -X POST 'https://beta.api.specifyapp.com/repository/{owner}/{name}/design-tokens' \
  -H 'Authorization: <personal access token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

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's servers.

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

Attributes

All errors returned by the API include the following data elements:

  • type string

    The type of error returned. One of api_connection_error, api_error, authentication_error, invalid_request_error, or rate_limit_error.

  • statusCode string

    For some errors that could be handled programmatically, a short string indicating the error code reported.

  • message string

    A human-readable message providing more details about the error.

  • validation array

    All invalid query / payload parameters. All invalid query / payload parameters. This property will be displayed on specific endpoints error response.

HTTP status code summary

  • 200 - OK Everything worked as expected.
  • 401 - Unauthorised No valid API key provided.
  • 402 - Request Failed The parameters were valid but the request failed.
  • 403 - Forbidden The API key doesn't have permissions to perform the request.
  • 404 - Not Found The requested resource doesn't exist.
  • 409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
  • 500, 502, 503, 504 - Server Errors Something went wrong on Specify's end.

Error types

  • api_connection_error Failure to connect to Specify's API.
  • api_error API errors cover any other type of problem (e.g., a temporary problem with Specify's servers), and are extremely uncommon.
  • authentication_error Failure to properly authenticate yourself in the request.
  • invalid_request_error Invalid request errors arise when your request has invalid parameters.
  • rate_limit_error Too many requests hit the API too quickly.