# Admin API

{% hint style="info" %}
The API is an enterprise-only feature
{% endhint %}

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

Themes 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

**Body:**

* **`flowContent`**: The [Flow content](https://docs.formsort.com/flow-content-data-format) describing this revision.
* **`jsonSchema`** : The JSON schema describing the answers collected by this revision.

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

{% hint style="info" %}
The `environmentRevisionUuid` can be obtained using the [List environments for a flow ](#list-environments-for-a-flow)endpoint
{% endhint %}

**Responses**

* `200` - A JSON object with details of a Variant Revision at the `data` key.