Search
K
Links
Comment on page

Admin API

Programmatic access to flows, variants, and deployments using JSON.
The API is an enterprise-only feature

Setup

Authentication

Within the Studio's API Keys tab, new API keys can be generated.
To access any of the resources, include the API key as the X-API-KEY header.
To obtain the API specification as an OpenAPI JSON, you can access:
curl https://api.formsort.com/alpha/spec --header "X-API-KEY: {{YOUR API KEY}}"

Pagination

Many endpoints return arrays of objects, with the results in a data array, and a pagination object describing the result set.
{
"data": [
...
],
"pagination": {
"page": 1,
"perPage": 10,
"total": 152
}
}
You can pass the following URL query parameters to paginate through the results list.
  • page (optional) - integer representing the page number.
  • perPage (optional) - integer representing the number of results per page.

JSON

The API consumes and produces JSON data (application/json). The specific content of the JSON data is described below.

Readonly resources

The following API paths are available at https://api.formsort.com

Obtain specification

GET /alpha/spec
Responses
  • 200 - An OpenAPI 3.0 specification of this API.

List flows

GET /alpha/flows
This path returns a list of Flows.
Responses
  • 200 - A JSON object with a list of Flows at the data key
The shape of the Flow object is:
Flow:
type: object
properties:
label:
type: string
createdAt:
type: string
format: date-time
required:
- createdAt
- label

List variants for a flow

GET /alpha/flows/{flowLabel}/variants
This path returns a list of Variants for the specified Flow.
Parameters
  • flowLabel (required) - string representing the Flow label.
Responses
  • 200 - A JSON object with a list of Variants within the data key
The shape of a single variant is:
Variant:
type: object
properties:
label:
type: string
createdAt:
type: string
format: date-time
required:
- createdAt
- label

List environments for a flow

GET /alpha/flows/{flowLabel}/environments
This path returns a list of Environments for the specified flow
Parameters
  • flowLabel (required) - string representing the Flow label.
Responses
  • 200 - A JSON object with a list of Environments within the data key
The shape of the Environment object is:
Environment:
type: object
properties:
revisionUuid:
type: string
label:
type: string
integrations:
type: array
items:
type: object
properties:
type:
type: string
configuration:
type: object
required:
- revisionUuid
- label
- integrations

List deployments of a particular variant

GET /alpha/flows/{flowLabel}/variants/{variantLabel}/deployments
This path returns a list of Deployments for the specified Variant.
Parameters
  • flowLabel (required) - string representing the Flow label.
  • variantLabel (required) - string representing the Variant label.
Responses
  • 200 - A JSON object with a list of Deployments within the data key
The shape of the Deployment object is:
Deployment:
type: object
properties:
deployedBy:
type: object
properties:
email:
type: string
required:
- email
deployedAt:
type: string
format: date-time
notes:
type: string
nullable: true
variantRevision:
type: object
properties:
uuid:
type: string
required:
- uuid
environment:
"$ref": "#/components/schemas/Environment"
required:
- deployedAt
- deployedBy
- environment

List available themes

GET /alpha/themes
This path returns the list of themes within the workspace.
Responses
  • 200 A JSON object with the list of Theme at the data key
Theme look like
Theme:
type: object
properties:
label:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time

Get details of a specific variant revision

GET /alpha/variant-revisions/{uuid}
This path returns details of a Variant Revision.
Parameters
  • uuid (required) - string representing the UUID of the Variant Revision.
Responses
  • 200 - A JSON object with details of a Variant Revision at the data key.

Action resources

Create a new deployment of a variant revision

POST /alpha/deployment
Create a new deployment of a variant revision.
Body
A JSON object with, at the minimum, variantRevisionUuid, environmentRevisionUuid, and isSuperseding.
DeploymentBody:
type: object
properties:
ignoreSupersededAnswers:
type: boolean
isSuperseding:
type: boolean
notes:
type: string
variantRevisionUuid:
type: string
environmentRevisionUuid:
type: string
required:
- isSuperseding
- environmentRevisionUuid
- variantRevisionUuid
The environmentRevisionUuid can be obtained using the List environments for a flow endpoint
Responses
  • 200 - A JSON object with details of a Variant Revision at the data key.