Back to top

Previz API

This describes the resources that make up the official Previz REST API v2. If you have any problems or requests please contact support.

Conventions

Wherever British English and American English spellings differ, the following rules apply:

  • All documentation uses British English, because we’re not savages.

  • All code–including the API endpoints–uses American English, because USA! USA!

API versions

The API uses content negotiation to serve the correct version, as follows.

Accept: application/vnd.previz.v2+json

If you do not request a specific version of the API, we will assume you want to use the current version. As future versions of the API may introduce breaking changes, we strongly encourage you to include the version header in all API requests.

Schema

The API is served over HTTPS, from https://app.previz.co/api.

  • All data is sent and received as JSON.

  • Timestamps use the ISO 8601 format. For example: 2017-01-23T09:23:15+00:00.

Authentication

The API expects an OAuth2 token in the header of each request.

Authorization: Bearer abc123

If a bearer token is not provided, the API returns a 401 response. If a bearer token is provided, but it does not afford the necessary privileges, the API returns a 403 response. More information regarding API responses is available in the HTTP status codes section.

HTTP verbs

The Previz API uses the appropriate HTTP verb for each action.

Verb Description
HEAD Used for retrieving a resource’s HTTP header information.
GET Used for retrieving resources.
POST Used for creating resources.
PATCH Used for updating resources with partial JSON data.
DELETE Used for deleting resources.
OPTIONS Used for retrieving details of the supported HTTP verbs.

HTTP status codes

The Previz API attempts to return appropriate HTTP status codes for every request.

Code Text Description
200 OK Everything worked as expected.
201 Created The resource was created.
400 Bad Request The request was unacceptable. This is often due to a missing (required) parameter.
401 Unauthorized The request did not include a valid API token.
403 Forbidden The request is not permitted. This is typically due to a request for restricted resource.
404 Not Found The requested resource does not exist, or the requested endpoint is not supported.
500 Internal Server Error Something went wrong on our end.

Errors

Application-specific error codes are not currently supported. These may be implemented in the future, as demand dictates.

Whenever an error occurs, we return a JSON response with the following structure.

{
    "errors": [
        {
            "title": "OAuth Exception",
            "detail": "Session expired at unix time 1385243766. The current unix time is 1385848532."
        }
    ]
}

Additional information is provided in the endpoint documentation.

Pagination

In an attempt to avoid repetition, the page pagination parameter is not documented on individual endpoints.

Pagination is supported on any GET endpoint which may return more than one resource. By default, 25 items per “page” are returned. If an endpoint overrides this default, it is noted in the documentation for the endpoint.

The next or previous “page” of results may be requested by specifying the page argument, but a much better option is the use the pagination.previous and pagination.next links from the pagination.links array.

{
    "data": [],
    "pagination": {
        "current_count": 20,
        "total_count": 52,
        "items_per_page": 20,
        "current_page": 2,
        "total_pages": 3,
        "links": [
            {
                "rel": "self",
                "url": "/example-resource?page=2"
            },
            {
                "rel": "pagination.first",
                "url": "/example-resource?page=1"
            },
            {
                "rel": "pagination.last",
                "url": "/example-resource?page=3"
            },
            {
                "rel": "pagination.previous",
                "url": "/example-resource?page=1"
            },
            {
                "rel": "pagination.next",
                "url": "/example-resource?page=3"
            }
        ]
    }
}

Hypermedia

Each resource may include a links property, which includes explicit links to related resources and sub-resources. API clients should use these canonical URLs, rather than attempting to construct a URL from its constituent parts.

Each link consists of:

  • A rel property, which uniquely identifies the link type.

  • A url property, which contains the endpoint URL.

  • An allows property, which lists the HTTP verbs supported by the endpoint.

{
    "data": {},
    "links": [
        {
            "rel": "self",
            "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397"
            "allows": [
                "DELETE",
                "GET",
                "OPTIONS",
                "PATCH"
            ]
        },
        {
            "rel": "team.projects",
            "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397/projects"
            "allows": [
                "GET",
                "OPTIONS",
                "POST"
            ]
        }
    ]
}

Sub-resources

Many resources include “sub-resources”. For example, a project contains (among other things) assets and scenes.

In order to avoid transferring unneeded data, results do not typically include these sub-resources by default. However, you may request that they be included using the include query string parameter.

For example, to include assets and scenes when retrieving a project, you would make the following request:

GET /projects/2b06cb34-72a8-4437-96f4-ee05cc792397?include=assets,scenes

It’s also common for sub-resources to include their own sub-resources. For example, a scene contains bookmarks and tracks. You may request that sub-sub-resources be included using “dot” syntax. For example, to include a scene’s bookmarks when retrieving a project, you would make the following request:

GET /projects/2b06cb34-72a8-4437-96f4-ee05cc792397?include=assets,scenes,scenes.bookmarks

Each endpoint details the supported sub-resources. Refer to the documentation for the sub-resource to find out which sub-sub-resources, if any, are supported.

Accounts

Account Collections

GET/accounts

Return a collection of unlocked accounts.

Example URI

GET /accounts
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "is_locked": false,
        "is_on_trial": false,
        "has_card": true,
        "has_unlimited_projects": false,
        "has_unlimited_storage": false,
        "has_unlimited_members": true,
        "billing_amount": 19999,
        "billing_interval": "month",
        "card_type": "mastercard",
        "card_last_four": "5995",
        "member_count": 5,
        "member_limit": 10,
        "project_count": 12,
        "project_limit": 20,
        "storage_limit": 10000,
        "storage_used": 650,
        "trial_ends_at": "2017-01-23T10:30:00+00:00",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/accounts/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "account.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "account.plan",
          "url": "/plans/2b06cb34-72a8-4437-96f4-ee05cc792397"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

POST/accounts

Example URI

POST /accounts
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "john@doe.com",
  "name": "John Doe",
  "password": "this-password-is-impressing-you",
  "plan_id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
  "stripe_token": "abc-123",
  "team_name": "The Mystic Rivers"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The account owner's email address."
    },
    "name": {
      "type": "string",
      "description": "The account owner's name."
    },
    "password": {
      "type": "string",
      "description": "The account owner's password."
    },
    "plan_id": {
      "type": "string",
      "description": "The plan ID."
    },
    "stripe_token": {
      "type": "string",
      "description": "The Stripe token. Required, if the plan ID refers to a paid plan."
    },
    "team_name": {
      "type": "string",
      "description": "The team name."
    }
  },
  "required": [
    "email",
    "name",
    "password",
    "plan_id",
    "team_name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "is_locked": false,
    "is_on_trial": false,
    "has_card": true,
    "has_unlimited_projects": false,
    "has_unlimited_storage": false,
    "has_unlimited_members": true,
    "billing_amount": 19999,
    "billing_interval": "month",
    "card_type": "mastercard",
    "card_last_four": "5995",
    "member_count": 5,
    "member_limit": 10,
    "project_count": 12,
    "project_limit": 20,
    "storage_limit": 10000,
    "storage_used": 650,
    "trial_ends_at": "2017-01-23T10:30:00+00:00",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/accounts/2b06cb34-72a8-4437-96f4-ee05cc792397"
    },
    {
      "rel": "account.owner",
      "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397"
    },
    {
      "rel": "account.plan",
      "url": "/plans/2b06cb34-72a8-4437-96f4-ee05cc792397"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "is_locked": {
          "type": "boolean",
          "description": "Whether the account is \"locked\"."
        },
        "is_on_trial": {
          "type": "boolean",
          "description": "Whether the account is still within its trial period."
        },
        "has_card": {
          "type": "boolean",
          "description": "Whether a credit card is associated with this account."
        },
        "has_unlimited_projects": {
          "type": "boolean",
          "description": "Whether the account includes unlimited projects."
        },
        "has_unlimited_storage": {
          "type": "boolean",
          "description": "Whether the account includes unlimited storage."
        },
        "has_unlimited_members": {
          "type": "boolean",
          "description": "Whether the account includes unlimited members."
        },
        "billing_amount": {
          "type": "number",
          "description": "The recurring billing amount, in cents."
        },
        "billing_interval": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "description": "The billing interval"
        },
        "card_type": {
          "type": "string",
          "description": "The payment card type, if applicable."
        },
        "card_last_four": {
          "type": "string",
          "description": "The last 4 digits of the payment card, if applicable."
        },
        "member_count": {
          "type": "number",
          "description": "The number of members associated with this account."
        },
        "member_limit": {
          "type": "number",
          "description": "The maximum number of members which may be associated with this account."
        },
        "project_count": {
          "type": "number",
          "description": "The number of projects associated with this account."
        },
        "project_limit": {
          "type": "number",
          "description": "The maximum number of projects which may be associated with this account."
        },
        "storage_limit": {
          "type": "number",
          "description": "The total storage (in MB) available to this account."
        },
        "storage_used": {
          "type": "number",
          "description": "The amount of storage (in MB) used by this account."
        },
        "trial_ends_at": {
          "type": "string",
          "description": "The date and time on which the trial ends."
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "account.owner"
              ]
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "account.plan"
              ]
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  422
HideShow

Returned if the given data failed validation.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/accounts

Example URI

OPTIONS /accounts
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS,POST
Body
{
  "allows": [
    "GET",
    "OPTIONS",
    "POST"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Account

GET/accounts/{account_id}

Example URI

GET /accounts/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
account_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited account IDs.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "is_locked": false,
        "is_on_trial": false,
        "has_card": true,
        "has_unlimited_projects": false,
        "has_unlimited_storage": false,
        "has_unlimited_members": true,
        "billing_amount": 19999,
        "billing_interval": "month",
        "card_type": "mastercard",
        "card_last_four": "5995",
        "member_count": 5,
        "member_limit": 10,
        "project_count": 12,
        "project_limit": 20,
        "storage_limit": 10000,
        "storage_used": 650,
        "trial_ends_at": "2017-01-23T10:30:00+00:00",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/accounts/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "account.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "account.plan",
          "url": "/plans/2b06cb34-72a8-4437-96f4-ee05cc792397"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given account IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

DELETE/accounts/{account_id}

Example URI

DELETE /accounts/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
account_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single account ID.

Response  204
HideShow
Headers
Content-Type: application/json
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given project ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

PATCH/accounts/{account_id}

Example URI

PATCH /accounts/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
account_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single account ID.

Request
HideShow
Body
{
  "is_locked": true,
  "member_limit": 10,
  "plan_id": "2b06cb34-72a8-4437-96f4-ee05cc792397"
}
Schema
{
  "type": "object",
  "properties": {
    "is_locked": {
      "type": "boolean",
      "description": "A boolean value, specifying whether the account is locked."
    },
    "member_limit": {
      "type": "number",
      "description": "The maximum number of members which may be associated with this account."
    },
    "plan_id": {
      "type": "string",
      "description": "The ID of the desired plan."
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "is_locked": false,
    "is_on_trial": false,
    "has_card": true,
    "has_unlimited_projects": false,
    "has_unlimited_storage": false,
    "has_unlimited_members": true,
    "billing_amount": 19999,
    "billing_interval": "month",
    "card_type": "mastercard",
    "card_last_four": "5995",
    "member_count": 5,
    "member_limit": 10,
    "project_count": 12,
    "project_limit": 20,
    "storage_limit": 10000,
    "storage_used": 650,
    "trial_ends_at": "2017-01-23T10:30:00+00:00",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/accounts/2b06cb34-72a8-4437-96f4-ee05cc792397"
    },
    {
      "rel": "account.owner",
      "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397"
    },
    {
      "rel": "account.plan",
      "url": "/plans/2b06cb34-72a8-4437-96f4-ee05cc792397"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "is_locked": {
          "type": "boolean",
          "description": "Whether the account is \"locked\"."
        },
        "is_on_trial": {
          "type": "boolean",
          "description": "Whether the account is still within its trial period."
        },
        "has_card": {
          "type": "boolean",
          "description": "Whether a credit card is associated with this account."
        },
        "has_unlimited_projects": {
          "type": "boolean",
          "description": "Whether the account includes unlimited projects."
        },
        "has_unlimited_storage": {
          "type": "boolean",
          "description": "Whether the account includes unlimited storage."
        },
        "has_unlimited_members": {
          "type": "boolean",
          "description": "Whether the account includes unlimited members."
        },
        "billing_amount": {
          "type": "number",
          "description": "The recurring billing amount, in cents."
        },
        "billing_interval": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "description": "The billing interval"
        },
        "card_type": {
          "type": "string",
          "description": "The payment card type, if applicable."
        },
        "card_last_four": {
          "type": "string",
          "description": "The last 4 digits of the payment card, if applicable."
        },
        "member_count": {
          "type": "number",
          "description": "The number of members associated with this account."
        },
        "member_limit": {
          "type": "number",
          "description": "The maximum number of members which may be associated with this account."
        },
        "project_count": {
          "type": "number",
          "description": "The number of projects associated with this account."
        },
        "project_limit": {
          "type": "number",
          "description": "The maximum number of projects which may be associated with this account."
        },
        "storage_limit": {
          "type": "number",
          "description": "The total storage (in MB) available to this account."
        },
        "storage_used": {
          "type": "number",
          "description": "The amount of storage (in MB) used by this account."
        },
        "trial_ends_at": {
          "type": "string",
          "description": "The date and time on which the trial ends."
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "account.owner"
              ]
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "account.plan"
              ]
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given account ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/accounts/{account_id}

Example URI

OPTIONS /accounts/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
account_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single account ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: DELETE,GET,OPTIONS,PATCH
Body
{
  "allows": [
    "DELETE",
    "GET",
    "OPTIONS",
    "PATCH"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Locked Account Collections

GET/accounts/locked

Example URI

GET /accounts/locked
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "is_locked": false,
        "is_on_trial": false,
        "has_card": true,
        "has_unlimited_projects": false,
        "has_unlimited_storage": false,
        "has_unlimited_members": true,
        "billing_amount": 19999,
        "billing_interval": "month",
        "card_type": "mastercard",
        "card_last_four": "5995",
        "member_count": 5,
        "member_limit": 10,
        "project_count": 12,
        "project_limit": 20,
        "storage_limit": 10000,
        "storage_used": 650,
        "trial_ends_at": "2017-01-23T10:30:00+00:00",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/accounts/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "account.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "account.plan",
          "url": "/plans/2b06cb34-72a8-4437-96f4-ee05cc792397"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/accounts/locked

Example URI

OPTIONS /accounts/locked
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Assets

Projects assets.

Asset Collections

GET/assets

Not supported.

Example URI

GET /assets
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/assets

Example URI

OPTIONS /assets
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS
Body
{
  "allows": [
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Asset

GET/assets/{asset_id}

Example URI

GET /assets/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
asset_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited asset IDs.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "original": {
          "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
          "class": "original",
          "file_name": "kitten.jpg",
          "url": "https://assets.previz.co/account-12345/abcxyz123.jpg",
          "status": "ready",
          "created_at": "2017-01-02T09:23:44+00:00",
          "updated_at": "2017-01-23T10:04:16+00:00"
        },
        "variants": [
          {
            "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
            "class": "thumb",
            "file_name": "kitten-lowres.jpg",
            "url": "https://assets.previz.co/account-12345/abcxyz123-lowres.jpg",
            "status": "pending",
            "created_at": "2017-01-02T09:23:44+00:00",
            "updated_at": "2017-01-23T10:04:16+00:00"
          }
        ],
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/assets/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "asset.project",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given asset IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/assets/{asset_id}

Example URI

OPTIONS /assets/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
asset_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single asset ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Bookmarks

Scene bookmarks.

Bookmarks Collections

GET/bookmarks

Not supported.

Example URI

GET /bookmarks
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/bookmarks

Example URI

OPTIONS /bookmarks
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS
Body
{
  "allows": [
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Bookmark

GET/bookmarks/{bookmark_id}{?include}

Example URI

GET /bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397?include=scene
URI Parameters
HideShow
bookmark_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited bookmark IDs.

include
string (optional) Example: scene

A comma-delimited list of sub-resources to include. Valid values are:

  • owner

  • project

  • scene

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "title": "Example Bookmark Title",
        "position": {
          "x": 23.60132493456,
          "y": 5.0224258731906,
          "z": -27.827297609677
        },
        "target": {
          "x": -0.1155837886347,
          "y": 1.6984383010615,
          "z": 1.4066511520051
        },
        "order_index": 1,
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "bookmark.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "bookmark.project",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "bookmark.scene",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given bookmark IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/bookmarks/{bookmark_id}

Example URI

OPTIONS /bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
bookmark_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single bookmark ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Favourites

User-favourited resources.

Favourites Collections

GET/favorites

Not supported.

Example URI

GET /favorites
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/favorites

Example URI

OPTIONS /favorites
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS
Body
{
  "allows": [
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Favourite

GET/favorites/{favorite_id}{?include}

Example URI

GET /favorites/2b06cb34-72a8-4437-96f4-ee05cc792397?include=owner
URI Parameters
HideShow
favorite_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited favourite IDs.

include
string (optional) Example: owner

A comma-delimited list of sub-resources to include. Valid values are:

  • owner

  • resource

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/favorites/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "favorite.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "favorite.resource",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given user IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

DELETE/favorites/{favorite_id}

Example URI

DELETE /favorites/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
favorite_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single favourite ID.

Response  204
HideShow
Headers
Content-Type: application/json
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given favourite ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/favorites/{favorite_id}

Example URI

OPTIONS /favorites/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
favorite_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single favourite ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: DELETE,GET,OPTIONS
Body
{
  "allows": [
    "DELETE",
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Projects

Previz projects.

Project Collections

GET/projects{?include}

Retrieve all of the projects available to the authenticated user.

Example URI

GET /projects?include=scenes,team
URI Parameters
HideShow
include
string (optional) Example: scenes,team

A comma-delimited list of sub-resources to include. Valid values are:

  • assets

  • scenes

  • team

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "slug": "example-project-title",
        "title": "Example Project Title",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "project.assets",
          "url": "/assets/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "project.scenes",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "project.team",
          "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}

POST/projects

Create a new project.

Example URI

POST /projects
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A New Project",
  "team_id": "2b06cb34-72a8-4437-96f4-ee05cc792397"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The Project title."
    },
    "team_id": {
      "type": "string",
      "description": "The ID of the Team to which this Project belongs."
    }
  },
  "required": [
    "title",
    "team_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "slug": "example-project-title",
    "title": "Example Project Title",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "project.assets",
      "url": "/assets/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "project.scenes",
      "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "project.team",
      "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "project.assets"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "project.scenes"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "project.team"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  400
HideShow

Returned if the given data failed validation.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/projects

Example URI

OPTIONS /projects
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS,POST
Body
{
  "allows": [
    "GET",
    "OPTIONS",
    "POST"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Project

GET/projects/{project_id}{?include}

Example URI

GET /projects/2b06cb34-72a8-4437-96f4-ee05cc792397?include=
URI Parameters
HideShow
project_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited project IDs.

include
string (optional) 

A comma-delimited list of sub-resources to include. Valid values are:

  • assets

  • scenes

  • team

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "slug": "example-project-title",
        "title": "Example Project Title",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "project.assets",
          "url": "/assets/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "project.scenes",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "project.team",
          "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given project IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

PATCH/projects/{project_id}

Example URI

PATCH /projects/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
project_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single project ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A New Project Title"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    }
  },
  "required": [
    "title"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "slug": "example-project-title",
    "title": "Example Project Title",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "project.assets",
      "url": "/assets/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "project.scenes",
      "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "project.team",
      "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "project.assets"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "project.scenes"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "project.team"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if a project with the given ID could not be found.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

DELETE/projects/{project_id}

Example URI

DELETE /projects/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
project_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single project ID.

Response  204
HideShow
Headers
Content-Type: application/json
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given project ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/projects/{project_id}

Example URI

OPTIONS /projects/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
project_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single project ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: DELETE,GET,OPTIONS,PATCH
Body
{
  "allows": [
    "DELETE",
    "GET",
    "OPTIONS",
    "PATCH"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Scenes

Project scenes.

Scene Collections

GET/scenes

Not supported.

Example URI

GET /scenes
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

POST/scenes

Create a new scene.

Example URI

POST /scenes
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A New Scene",
  "project_id": "2b06cb34-72a8-4437-96f4-ee05cc792397"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "project_id": {
      "type": "string",
      "description": "The ID of the Project to which this Scene belongs."
    }
  },
  "required": [
    "title",
    "project_id"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "is_json_ready": true,
    "title": "Scene Title",
    "order_index": 1,
    "settings_blob": {},
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00",
    "json_updated_at": "2017-01-02T09:30:00+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.json",
      "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.project",
      "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.tracks",
      "url": "/tracks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.bookmarks",
      "url": "/bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "is_json_ready": {
          "type": "boolean",
          "description": "Is the scene JSON ready? If the JSON has not been uploaded, or is still being processed, this will be false."
        },
        "title": {
          "type": "string"
        },
        "order_index": {
          "type": "number"
        },
        "settings_blob": {
          "type": "object",
          "properties": {},
          "description": "The parsed JSON \"settings\" blob."
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "json_updated_at": {
          "type": "string",
          "description": "The time at which the JSON was last updated."
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.json"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.project"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.tracks"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.bookmarks"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  400
HideShow

Returned if the given data failed validation.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/scenes

Example URI

OPTIONS /scenes
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS,POST
Body
{
  "allows": [
    "OPTIONS",
    "POST"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Project Scene Collections

GET/scenes{?project_id,include}

Retrieve all of the scenes associated with the specified project.

Example URI

GET /scenes?project_id=2b06cb34-72a8-4437-96f4-ee05cc792397&include=bookmarks,tracks
URI Parameters
HideShow
project_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

The ID of the “parent” project.

include
string (optional) Example: bookmarks,tracks

A comma-delimited list of sub-resources to include. Valid values are:

  • bookmarks

  • project

  • tracks

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "is_json_ready": true,
        "title": "Scene Title",
        "order_index": 1,
        "settings_blob": {},
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00",
        "json_updated_at": "2017-01-02T09:30:00+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.json",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.project",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.tracks",
          "url": "/tracks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.bookmarks",
          "url": "/bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given project ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/scenes{?project_id}

Example URI

OPTIONS /scenes?project_id=2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
project_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

The ID of the “parent” project.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Scene

GET/scenes/{scene_id}{?include}

Example URI

GET /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397?include=bookmarks,tracks
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited scene IDs.

include
string (optional) Example: bookmarks,tracks

A comma-delimited list of sub-resources to include. Valid values are:

  • bookmarks

  • project

  • tracks

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "is_json_ready": true,
        "title": "Scene Title",
        "order_index": 1,
        "settings_blob": {},
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00",
        "json_updated_at": "2017-01-02T09:30:00+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.json",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.project",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.tracks",
          "url": "/tracks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "scene.bookmarks",
          "url": "/bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given scene IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

PATCH/scenes/{scene_id}

Example URI

PATCH /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single scene ID.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A New Scene Title"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    }
  },
  "required": [
    "title"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "is_json_ready": true,
    "title": "Scene Title",
    "order_index": 1,
    "settings_blob": {},
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00",
    "json_updated_at": "2017-01-02T09:30:00+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.json",
      "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.project",
      "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.tracks",
      "url": "/tracks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "scene.bookmarks",
      "url": "/bookmarks/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "is_json_ready": {
          "type": "boolean",
          "description": "Is the scene JSON ready? If the JSON has not been uploaded, or is still being processed, this will be false."
        },
        "title": {
          "type": "string"
        },
        "order_index": {
          "type": "number"
        },
        "settings_blob": {
          "type": "object",
          "properties": {},
          "description": "The parsed JSON \"settings\" blob."
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "json_updated_at": {
          "type": "string",
          "description": "The time at which the JSON was last updated."
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.json"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.project"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.tracks"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "scene.bookmarks"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if a scene with the given ID could not be found.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

DELETE/scenes/{scene_id}

Example URI

DELETE /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single scene ID.

Response  204
HideShow
Headers
Content-Type: application/json
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given scene ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/scenes/{scene_id}

Example URI

OPTIONS /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single scene ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: DELETE,GET,OPTIONS,PATCH
Body
{
  "allows": [
    "DELETE",
    "GET",
    "OPTIONS",
    "PATCH"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Scene JSON

GET/scenes/{scene_id}/json

Example URI

GET /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single scene ID.

Response  200
HideShow
Headers
Content-Type: application/json
Content-Disposition: attachment
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given scene ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

PUT/scenes/{scene_id}/json

Expects the request body to be valid JSON.

Example URI

PUT /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single scene ID.

Response  204
HideShow
Headers
Content-Type: application/json
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given scene ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/scenes/{scene_id}/json

Example URI

OPTIONS /scenes/2b06cb34-72a8-4437-96f4-ee05cc792397/json
URI Parameters
HideShow
scene_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single scene ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS,PUT
Body
{
  "allows": [
    "GET",
    "OPTIONS",
    "PUT"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Teams

Previz teams.

Team Collections

GET/teams{?include}

Retrieve all of the teams available to the authenticated user.

Example URI

GET /teams?include=owner,projects
URI Parameters
HideShow
include
string (optional) Example: owner,projects

A comma-delimited list of sub-resources to include. Valid values are:

  • owner

  • projects

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "title": "Example Team Title",
        "slug": "example-team-title",
        "avatar_url": "https://assets.previz.co/account-12345/abcxyz123.png",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "team.projects",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "team.members",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "team.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}

OPTIONS/teams

Example URI

OPTIONS /teams
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Team

GET/teams/{team_id}{?include}

Example URI

GET /teams/2b06cb34-72a8-4437-96f4-ee05cc792397?include=projects
URI Parameters
HideShow
team_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited team IDs.

include
string (optional) Example: projects

A comma-delimited list of sub-resources to include. Valid values are:

  • owner

  • projects

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "title": "Example Team Title",
        "slug": "example-team-title",
        "avatar_url": "https://assets.previz.co/account-12345/abcxyz123.png",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/teams/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "team.projects",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "team.members",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "team.owner",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given team IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/teams/{team_id}

Example URI

OPTIONS /teams/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
team_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single team ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Timelines

Track timelines.

Timeline Collections

GET/timelines

Not supported.

Example URI

GET /timelines
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/timelines

Example URI

OPTIONS /timelines
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS
Body
{
  "allows": [
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Timeline

GET/timelines/{timeline_id}{?include}

Example URI

GET /timelines/2b06cb34-72a8-4437-96f4-ee05cc792397?include=track
URI Parameters
HideShow
timeline_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited timeline IDs.

include
string (optional) Example: track

A comma-delimited list of sub-resources to include. Valid values are:

  • project

  • track

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "json": "Hello, world!",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/timelines/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "timeline.project",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "timeline.track",
          "url": "/tracks/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given timeline IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/timelines/{timeline_id}

Example URI

OPTIONS /timelines/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
timeline_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single timeline ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Tracks

Scene tracks.

Tracks Collections

GET/tracks

Not supported.

Example URI

GET /tracks
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/tracks

Example URI

OPTIONS /tracks
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS
Body
{
  "allows": [
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Track

GET/tracks/{track_id}{?include}

Example URI

GET /tracks/2b06cb34-72a8-4437-96f4-ee05cc792397?include=timelines
URI Parameters
HideShow
track_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited track IDs.

include
string (optional) Example: timelines

A comma-delimited list of sub-resources to include. Valid values are:

  • project

  • scene

  • timelines

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "title": "Example Track Title",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/tracks/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "track.project",
          "url": "/projects/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "track.scene",
          "url": "/scenes/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "track.timelines",
          "url": "/timelines/2b06cb34-72a8-4437-96f4-ee05cc792397,2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given track IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/tracks/{track_id}

Example URI

OPTIONS /tracks/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
track_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single track ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Users

Previz users.

Users Collections

GET/users

Not supported.

Example URI

GET /users
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/users

Example URI

OPTIONS /users
Response  200
HideShow
Headers
Content-Type: application/json
Allow: OPTIONS
Body
{
  "allows": [
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

User

GET/users/{user_id}{?include}

Example URI

GET /users/2b06cb34-72a8-4437-96f4-ee05cc792397?include=teams
URI Parameters
HideShow
user_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited user IDs.

include
string (optional) Example: teams

A comma-delimited list of sub-resources to include. Valid values are:

  • teams
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "avatar_url": "https://assets.previz.co/avatars/johndoe.jpg",
        "email": "john@doe.com",
        "full_name": "John Doe",
        "profile_prompt_status": "enabled",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "user.teams",
          "url": "/user/2b06cb34-72a8-4437-96f4-ee05cc792397/teams",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given user IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

PATCH/users/{user_id}

Example URI

PATCH /users/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
user_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single user ID.

Request
HideShow
Body
{
  "email": "john@doe.com",
  "name": "John Doe",
  "password": "1337 hackorz",
  "profile_prompt_status": "enabled"
}
Schema
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "profile_prompt_status": {
      "enum": [
        "enabled",
        "disabled",
        "muted"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "avatar_url": "https://assets.previz.co/avatars/johndoe.jpg",
    "email": "john@doe.com",
    "full_name": "John Doe",
    "profile_prompt_status": "enabled",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "user.teams",
      "url": "/user/2b06cb34-72a8-4437-96f4-ee05cc792397/teams",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "avatar_url": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "full_name": {
          "type": "string"
        },
        "profile_prompt_status": {
          "type": "string",
          "enum": [
            "enabled",
            "disabled",
            "muted"
          ],
          "default": "enabled"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rel": {
            "type": "string",
            "enum": [
              "user.teams"
            ]
          },
          "url": {
            "type": "string"
          },
          "allows": {
            "type": "array",
            "description": "An array of the supported HTTP verbs."
          }
        },
        "required": [
          "rel"
        ]
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given user IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/users/{user_id}

Example URI

OPTIONS /users/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
user_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single user ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS,PATCH
Body
{
  "allows": [
    "GET",
    "OPTIONS",
    "PATCH"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Email Check

HEAD/users/emails/{email}

Used to check whether the given email address is associated with a user.

Example URI

HEAD /users/emails/john@doe.com
URI Parameters
HideShow
email
string (required) Example: john@doe.com

The email address.

Response  200
Response  404

OPTIONS/users/emails/{email}

Example URI

OPTIONS /users/emails/john@doe.com
URI Parameters
HideShow
email
string (required) Example: john@doe.com

The email address.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: HEAD,OPTIONS
Body
{
  "allows": [
    "HEAD",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

ProjectShares

ProjectShares.

Share Collections

View all shares
GET/shares{?project_id,include}

Retrieve all of the project shares associated with the specified project.

Example URI

GET /shares?project_id=1&include=project
URI Parameters
HideShow
project_id
string (required) Example: 1

The ID of the “parent” project.

include
string (optional) Example: project

A comma-delimited list of sub-resources to include. Valid values are:

  • project
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "1",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/shares/1"
        },
        {
          "rel": "share.project",
          "url": "/projects/999"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given project ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Share

View a share
GET/shares/{share_id}{?include}

Example URI

GET /shares/123,456?include=project
URI Parameters
HideShow
share_id
string (required) Example: 123,456

One or more comma-delimited share IDs.

include
string (optional) Example: project

A comma-delimited list of sub-resources to include. Valid values are:

  • project
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "1",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/shares/1"
        },
        {
          "rel": "share.project",
          "url": "/projects/999"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given scene IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

Current User

The me endpoints allow the client to perform actions related to the authenticated user. For the sake of convenience, we refer to the authenticated user as the “current” user.

Me

GET/me{?include}

Example URI

GET /me?include=teams
URI Parameters
HideShow
include
string (optional) Example: teams

A comma-delimited list of sub-resources to include. Valid values are:

  • teams
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "avatar_url": "https://assets.previz.co/avatars/johndoe.jpg",
    "email": "john@doe.com",
    "full_name": "John Doe",
    "profile_prompt_status": "enabled",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "user.teams",
      "url": "/user/2b06cb34-72a8-4437-96f4-ee05cc792397/teams",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "avatar_url": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "full_name": {
          "type": "string"
        },
        "profile_prompt_status": {
          "type": "string",
          "enum": [
            "enabled",
            "disabled",
            "muted"
          ],
          "default": "enabled"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rel": {
            "type": "string",
            "enum": [
              "user.teams"
            ]
          },
          "url": {
            "type": "string"
          },
          "allows": {
            "type": "array",
            "description": "An array of the supported HTTP verbs."
          }
        },
        "required": [
          "rel"
        ]
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

PATCH/me

Example URI

PATCH /me
Request
HideShow
Body
{
  "email": "john@doe.com",
  "name": "John Doe",
  "password": "1337 hackorz",
  "profile_prompt_status": "enabled"
}
Schema
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "profile_prompt_status": {
      "enum": [
        "enabled",
        "disabled",
        "muted"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "avatar_url": "https://assets.previz.co/avatars/johndoe.jpg",
    "email": "john@doe.com",
    "full_name": "John Doe",
    "profile_prompt_status": "enabled",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "user.teams",
      "url": "/user/2b06cb34-72a8-4437-96f4-ee05cc792397/teams",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "avatar_url": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "full_name": {
          "type": "string"
        },
        "profile_prompt_status": {
          "type": "string",
          "enum": [
            "enabled",
            "disabled",
            "muted"
          ],
          "default": "enabled"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rel": {
            "type": "string",
            "enum": [
              "user.teams"
            ]
          },
          "url": {
            "type": "string"
          },
          "allows": {
            "type": "array",
            "description": "An array of the supported HTTP verbs."
          }
        },
        "required": [
          "rel"
        ]
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/me

Example URI

OPTIONS /me
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS,PATCH
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugins

Previz software plugins. Plugin endpoints do not require authentication, or authorisation.

Plugin Collections

GET/plugins{?include}

Retrieve all of the plugins available to the authenticated user.

Example URI

GET /plugins?include=versions
URI Parameters
HideShow
include
string (optional) Example: versions

A comma-delimited list of sub-resources to include. Valid values are:

  • versions
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "handle": "cinema4d",
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "title": "Cinema4D",
        "description": "Create Previz projects and export meshes, UV sets and images directly from Cinema 4D.",
        "current_version": "1.1.3",
        "released_at": "2017-01-02T09:23:44+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "plugin.download",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "plugin.icon",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/icon.png",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "plugin.versions",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}

OPTIONS/plugins

Example URI

OPTIONS /plugins
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugin

GET/plugins/{plugin_id}{?include}

Example URI

GET /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397?include=
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited plugin IDs.

include
string (optional) 

A comma-delimited list of sub-resources to include. Valid values are:

  • versions
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "handle": "cinema4d",
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "title": "Cinema4D",
        "description": "Create Previz projects and export meshes, UV sets and images directly from Cinema 4D.",
        "current_version": "1.1.3",
        "released_at": "2017-01-02T09:23:44+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "plugin.download",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "plugin.icon",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/icon.png",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "plugin.versions",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  404
HideShow

Returned if any of the given plugin IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/plugins/{plugin_id}

Example URI

OPTIONS /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugin Version Collections

GET/plugins/{plugin_id}/versions

Example URI

GET /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "released_at": "2017-01-02T09:23:44+00:00",
        "version": "1.1.3"
      },
      "links": [
        {
          "rel": "self",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "version.plugin",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "version.download",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  404
HideShow

Returned if the given plugin ID does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/plugins/{plugin_id}/versions

Example URI

OPTIONS /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugin Version

GET/plugins/{plugin_id}/versions/{version_id}

Example URI

GET /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

version_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited plugin version IDs.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "released_at": "2017-01-02T09:23:44+00:00",
        "version": "1.1.3"
      },
      "links": [
        {
          "rel": "self",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "version.plugin",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397"
        },
        {
          "rel": "version.download",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397"
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  404
HideShow

Returned if the given plugin ID does not exist, or any of the given plugin version IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/plugins/{plugin_id}/versions/{version_id}

Example URI

OPTIONS /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/versions/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

version_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin version ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugin Download

GET/plugins/{plugin_id}/downloads/{version_id}

Example URI

GET /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

version_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin version ID, or the special keyword latest.

Response  200
HideShow
Headers
Content-Type: application/zip
Content-Disposition: attachment; filename="example-v110.zip"
Response  404
HideShow

Returned if the given plugin or plugin version does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/plugins/{plugin_id}/downloads/{version_id}

Example URI

OPTIONS /plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
plugin_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin ID.

version_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single plugin version ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugin Share Collections

GET/plugins/shares{?include}

Retrieve all of the plugin shares available to the authenticated user.

Example URI

GET /plugins/shares?include=sharer
URI Parameters
HideShow
include
string (optional) Example: sharer

A comma-delimited list of sub-resources to include. Valid values are:

  • sharer
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "recipient_email": "john@doe.com",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/plugins/shares/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "share.download",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "share.plugin",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "share.sharer",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}

POST/plugins/shares

Email a personalised link to the given recipient(s), to download the latest version of the specified plugin.

Example URI

POST /plugins/shares
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "plugin_id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
  "version_id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
  "recipient_email": "john@doe.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "plugin_id": {
      "type": "string",
      "description": "A single plugin ID."
    },
    "version_id": {
      "type": "string",
      "description": "A single plugin version ID. If not supplied, defaults to the latest version."
    },
    "recipient_email": {
      "type": "string"
    }
  },
  "required": [
    "plugin_id",
    "recipient_email"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
    "recipient_email": "john@doe.com",
    "created_at": "2017-01-02T09:23:44+00:00",
    "updated_at": "2017-01-23T10:04:16+00:00"
  },
  "links": [
    {
      "rel": "self",
      "url": "/plugins/shares/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "share.download",
      "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "share.plugin",
      "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    },
    {
      "rel": "share.sharer",
      "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
      "allows": [
        "OPTIONS"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "recipient_email": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "links": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "self"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "share.download"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "share.plugin"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        },
        {
          "type": "object",
          "properties": {
            "rel": {
              "type": "string",
              "enum": [
                "share.sharer"
              ]
            },
            "url": {
              "type": "string"
            },
            "allows": {
              "type": "array",
              "description": "An array of the supported HTTP verbs."
            }
          },
          "required": [
            "rel"
          ]
        }
      ]
    }
  }
}
Response  400
HideShow

Returned if the given data failed validation.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if the given plugin ID, or plugin version ID (if specified) does not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/plugins/shares

Example URI

OPTIONS /plugins/shares
Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS,POST
Body
{
  "allows": [
    "GET",
    "OPTIONS",
    "POST"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Plugin Share

GET/plugins/shares/{share_id}{?include}

Example URI

GET /plugins/shares/2b06cb34-72a8-4437-96f4-ee05cc792397?include=
URI Parameters
HideShow
share_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

One or more comma-delimited share IDs.

include
string (optional) 

A comma-delimited list of sub-resources to include. Valid values are:

  • sharer
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "data": {
        "id": "2b06cb34-72a8-4437-96f4-ee05cc792397",
        "recipient_email": "john@doe.com",
        "created_at": "2017-01-02T09:23:44+00:00",
        "updated_at": "2017-01-23T10:04:16+00:00"
      },
      "links": [
        {
          "rel": "self",
          "url": "/plugins/shares/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "share.download",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397/downloads/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "share.plugin",
          "url": "/plugins/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        },
        {
          "rel": "share.sharer",
          "url": "/users/2b06cb34-72a8-4437-96f4-ee05cc792397",
          "allows": [
            "OPTIONS"
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_count": 20,
    "total_count": 52,
    "items_per_page": 20,
    "current_page": 2,
    "total_pages": 3,
    "links": [
      {
        "rel": "self",
        "url": "/example-resource?page=2"
      },
      {
        "rel": "pagination.first",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.last",
        "url": "/example-resource?page=3"
      },
      {
        "rel": "pagination.previous",
        "url": "/example-resource?page=1"
      },
      {
        "rel": "pagination.next",
        "url": "/example-resource?page=3"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "current_count": {
          "type": "number",
          "description": "The number of items on the current page."
        },
        "total_count": {
          "type": "number",
          "description": "The total number of items."
        },
        "items_per_page": {
          "type": "number",
          "description": "The maximum number of items on each page."
        },
        "current_page": {
          "type": "number",
          "description": "The current page index (1-based)."
        },
        "total_pages": {
          "type": "number",
          "description": "The total number of pages."
        },
        "links": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "self"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.first"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.last"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.previous"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            },
            {
              "type": "object",
              "properties": {
                "rel": {
                  "type": "string",
                  "enum": [
                    "pagination.next"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "rel"
              ]
            }
          ]
        }
      }
    }
  }
}
Response  403
HideShow

Returned if the user is not authorised to perform this action.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Returned if any of the given share IDs do not exist.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "title": "Example Exception",
      "detail": "A description of the problem."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    }
  }
}

OPTIONS/plugins/shares/{share_id}

Example URI

OPTIONS /plugins/shares/2b06cb34-72a8-4437-96f4-ee05cc792397
URI Parameters
HideShow
share_id
string (required) Example: 2b06cb34-72a8-4437-96f4-ee05cc792397

A single share ID.

Response  200
HideShow
Headers
Content-Type: application/json
Allow: GET,OPTIONS
Body
{
  "allows": [
    "GET",
    "OPTIONS"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "allows": {
      "type": "array"
    }
  }
}

Generated by aglio on 17 Jul 2018