REST API
The Specify API lets you extend Specify functionalities beyond what we provide out of the box.
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.
Overview of the possibilities offered by the Specify 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.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-tokenspost
https://api.specifyapp.com/repository/{workspace}/{repository}/design-tokens
Get design tokens and assets from a Specify repository.
Parameters
Path
workspace*
The name of your organization in Specify.\
For instance, in this URL
https://specifyapp.com/@specifyapp/Seeds/color the workspace is "@specifyapp".name*
The name of the Specify repository containing the design data you're requesting.\
For instance, in this URL
https://specifyapp.com/@specifyapp/Seeds/color the repository is "Seeds".Body
filter
Object
parsers
Object or Array
Can contain an object or an array of objects. Each object corresponds to a specific
Responses
200: OK
Everything worked as expected.
401: Unauthorized
No valid API key provided.
403: Forbidden
The API key doesn
404: Not Found
The requested resource doesn
500: Internal Server Error
Something went wrong on Specify
Once you have your personal access token, you can pass it within the
Authorization header of your request.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"}]}'
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.
Property | Type | Description |
|---|---|---|
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 | string | All invalid query / payload parameters. All invalid query / payload parameters. This property will be displayed on specific endpoints error response. |
Last modified 3d ago