Introduction

Getting Started

https://api.editsquare.com/

Edit Square is an online platform that provides the ability to generate videos automatically or on-demand.

1. Your designer designs a video
2. We turn it into an Edit Square template
3. You use this API to generate Videos

See examples at https://editsquare.com/templates

Authentication

Access Tokens

Edit Square uses access tokens to allow access to the API. There are two types of tokens.

Temporary Tokens (JWT)

This can be retrieved from the /login endpoint. These tokens have a relatively short expiration time, and are thus the most secure option to use. The tokens are returned with a refresh_token that can be used to retrieve the next access token via the /refresh endpoint.

Static Tokens

This type of token can be provided upon request and never expires. They are less secure, but quite useful for server-to-server communication.

Contact us to generate a secure access token for you.

Passing Tokens via Query Parameter

?access_token={token}

Once you have your access token, there are two ways to pass it to the API. You can either pass the access_token as a query parameter.

Passing Tokens via Authorization Header

Authorization: Bearer {token}

Or you can pass the access_token in the request's Authorization Header as a Bearer token.

Login

POST /auth/login

Retrieve a temporary access token.

Request Body

{
	"email": "admin@example.com",
	"password": "3ditsqu4r3"
}

email required

Email address of the user you're retrieving the access token for.

password required

Password of the user.

Response Body

{
	"data": {
		"access_token": "wrpna1v...",
		"refresh_token": "tfViV9z...",
		"expires": 900000
	}
}

access_token string

Temporary access token to be used in follow-up requests.

refresh_token string

The token that can be used to retrieve a new access token through /auth/refresh.

expires integer

How long before the access token will expire. Value is in milliseconds.

Refresh

POST /auth/refresh

Retrieve a new access token using a refresh token.

Request Body

{
	"refresh_token": "tfViV9z..."
}

refresh_token required

The refresh token to use which was retrieved as part of the initial /auth/login process.

Response Body

{
	"data": {
		"access_token": "wrpna1v...",
		"refresh_token": "tfViV9z...",
		"expires": 900000
	}
}

access_token string

Temporary access token to be used in follow-up requests.

refresh_token string

The token that can be used to retrieve a new access token through /auth/refresh.

expires integer

How long before the access token will expire. Value is in milliseconds.

Logout

POST /auth/logout

Invalidate the refresh token thus destroying the user's session.

Request Body

{
	"refresh_token": "tfViV9z..."
}

refresh_token required

The refresh token to invalidate.

Query Parameters

Most API endpoints can be manipulated using the following parameters.

Fields

?fields=*,renders.*

Choose which fields to be returned in the queried dataset. This parameter supports dot notation to request nested relational fields. You can also use wildcards * to include all fields at a specifc depth.

Get all top-level fields.

*

Get all top-level and second-level relational fields.

*.*

Get all top-level and second-level fields within renders.

*,renders.*

Get only first_name and last_name fields.

first_name,last_name

Filters

?filter={ "first_name": { "_eq": "John" } }

Filters are used to only return items in a collection which match their conditions. The filter parameter rely on a specific JSON structure to define their rules.

Syntax

• Field - Any valid root field, relational field, or logical operaor.
• Operator - Any valid filter operator.
• Value - Any valid static value or dynamic variable.

{
	<field>: {
		<operator>: <value>
	}
}

Filter Operators

Relational Fields

You can target related values by nesting field names. For example, if you have a relational Many-to-One owner field, you can set a rule for the owner.first_name field using the following syntax.

{
	"owner": {
		"first_name": {
			"_eq": "John"
		}
	}
}

Logical Operators

You can nest or group multiple rules using the _and and _or logical operators. Each logical operator is assigned an array for filter rules allowing for more complex filtering.

{
	"_or": [
		{
			"_and": [
				{
					"user_created": {
						"_eq": "$CURRENT_USER"
					}
				},
				{
					"status": {
						"_in": ["published", "draft"]
					}
				}
			]
		},
		{
			"_and": [
				{
					"user_created": {
						"_neq": "$CURRENT_USER"
					}
				},
				{
					"status": {
						"_in": ["published"]
					}
				}
			]
		}
	]
}

Dynamic Variables

In addition to passing static values, you can also filter using the following dynamic variables.

• $CURRENT_USER - The key for the currently authenticated user.
• $NOW - The current timestamp.
• $NOW(<adjustment>) - The current timestamp plus/minus a given distance, for example $NOW(-1 year) or $NOW(+2 hours)

Search

?search=Edit Square

The search field allows you to perform a search on all string and text type fields within a collection. It's an easy way to search for an item without creating complex field filters - though it is far less optimised. It only searches the root item fields and not related item fields.

Sort

?sort=-date_created,owner.name

The search query parameter can be used to change the order of the returned results. Sorting defaults to ascending, but this can be reversed by appending a minus sign. Fields are prioritised by the order in the parameter. The dot notation can also be used when sorting by values in nested fields.

Limit

?limit=200

The limit query parameter can be used to change the maximum number of results to be returned. The default limit is set to 100. To get all items within a collection without a limit, -1 can be used. However, depending on the size of your colleciton, fetching unlimited data may result in degraded performance or timeouts.

Page

?page=200

The page query parameter can be used in conjunction with the limit parameter to offset results by calculating limit * page.

Aggregation

?aggregate[avg]=cost

Aggregation functions allow you to perform calculations on a set of values and return a single result.

Grouping

By default the aggregation query parameter will run on the entire collection. To allow for more flexible reporting you can combine the above aggregation filter with grouping. Grouping allows for running the aggregation function based on a shared value. This allows for queries such as "Total number of renders per month".

The groupBy query parameter allows for grouping on multiple fields simultaneously.

Total Count

Filter Count

Users

You can manage users you have access to.

The User Object

{
	"id": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
	"first_name": "John",
	"last_name": "Smith",
	"email": "admin@example.com",
	"role": "653925a9-970e-487a-bfc0-ab6c96affcdc",
	"accounts": ["5528ef9e-f947-11ed-be56-0242ac120002"],
	"accounts_owned": ["5528ef9e-f947-11ed-be56-0242ac120002"],
}

id uuid

Primary key of the user.

first_name string

First name of the user.

last_name string

Last name of the user.

email string

Email address of the user.

role uuid

Role of the user. Many-to-one to roles.

accounts uuid

Accounts the user is associated with. Many-to-many to accounts.

accounts_owned uuid

Accounts the user is the owner of. One-to-many to accounts.

Retrieve the Current User

GET /users/me

Retrieve the currently authenticated user.

Response Body

Returns the user object for the authenticated user.

Update the Current User

PATCH /users/me

Update the currently authenticated user.

Request Body

{
	"email": "new.email@example.com"
}

first_name string

First name of the user.

last_name string

Last name of the user.

email string

Email address of the user.

Response Body

Returns the user object for the authenticated user.

Accounts

You can manage users associated with your accounts (teams)

The Account Object

{
	"id": "00460b3b-7cb7-4ef0-a567-df594a8f807e",
	"name": "Leeroy Jenkins",
	"owner": "fae889aa-e2c5-4428-a5ea-ad51a1de1a34",
	"status": "active",
	"render_credits": {
		"amount": 25,
		"remaining": 25,
		"used": 0
	},
	"renders": ["03c4e368-b73a-4681-83fc-dbeca3c3bf05"],
	"subscriptions": ["8b376253-f648-476d-ae0d-a56d1fa310f5"],
	"projects": ["603c21a4-0f7d-425e-85cf-ddbb572a4175"]
}

id uuid

Primary key of the account.

name string

Name of the account the user.

owner uuid

Primary key of the user who owns & manages the account.

status string

Status of the account & whether it is active or not

render_credits object

Object of integers describing how many credits you have, how many you have left & how many you have used.

• amount integer Total amount of credits in your quota.

• remaining integer Total number of credits available.

• used integer Total number of credits used.

renders array

Array of uuids referencing renders associate with this account.

subscriptions array

Array of uuids referencing subscriptions relating to the this account.

projects array

Array of uuids referencing projects associate with this account.

List Accounts

GET /accounts

Returns an array of the account object.

Read Account

GET /accounts/:id

Returns the account object.

Update Account

PATCH /accounts/:id

Request Body

{
	"name": "My Updated Team Name"
}

name string

The name of the account.

Response Body

Returns the account object.

Projects

Your projects.

The Project Object

{
	"id": "a64b38cd-9873-45ee-bfca-d623eca49311",
	"user_created": "fae889aa-e2c5-4428-a5ea-ad51a1de1a34",
	"date_created": "2022-10-22T15:53:56.844Z",
	"date_updated": "2022-10-28T12:48:45.382Z",
	"poster": "https://editsquare.com/my-poster-url.com",
	"title": "Promo Video",
	"account": "00460b3b-7cb7-4ef0-a567-df594a8f807e",
	"status": "active",
	"template_reference": null,
	"renders": [ "03c4e368-b73a-4681-83fc-dbeca3c3bf05"]
},

id uuid

Primary key of the project.

user_created uuid

The user who created the project

date_created string

Data timestamp when the project was created.

date_updated string

Data timestamp when the project was last updated.

poster string

URL pointing to a poster frame of the project.

title string

The title of the project.

account uuid

The uuid of the account that this was created under.

status string

The status of the project. One of "active" or "deleted".

template_reference uuid

uuid of the public template that was used to create this project.

renders array

Array of renders that have been made from this project.

List Projects

GET /projects

Returns an array of the project object.

Read Project

GET /projects/:id

Returns the project object.

Update Project

PATCH /projects/:id

Request Body

{
	"title": "My New Project Name"
}

title string

The new title of the project.

Renders

Your renders

The Render Object

{
	"id": "5102b2f5-f8ed-4415-afcc-2e75ead27067",
	"date_created": "2023-03-24T12:10:16.667Z",
	"date_updated": "2023-03-24T12:10:17.872Z",
	"user_created": "fae889aa-e2c5-4428-a5ea-ad51a1de1a34",
	"process_id": "31b978ed-838c-4b68-8dee-caed544d9814",
	"account": "00460b3b-7cb7-4ef0-a567-df594a8f807e",
	"project": "a909371f-af62-413a-92ba-f96d1c0e84e7",
	"title": "Product Sale",
	"playback_id": null,
	"download_ready": false,
	"status": "processing",
	"data": {
		"name": "remove webhooks",
		"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec mollis aliquam ante in placerat.",
		"price": "£100.00",
		"priceText": "PRICE TEXT",
		"productImageUrl": "https://ucarecdn.com/63c4eb77-967a-4e3d-9b95-1a52c2c39324/-/preview/-/quality/smart/",
		"bannerText": "BANNER TEXT",
		"color": "#D321AC",
		"bgColor": "#288C9E",
		"bgColorOpacity": "0.5",
		"bgBlendMode": "color"
	},
	"output": null
},

id uuid

Primary key of the render.

user_created uuid

The user who created the render.

date_created string

Data timestamp when the render was created.

date_updated string

Data timestamp when the render was last updated.

account uuid

uuid of the account associated with this render.

project uuid

uuid of the project associated with this render.

title string

The name of the project.

playback_id string

uuid of the final video output. Used for playback.

download_ready boooleon

States whether the video is ready for download.

status status

The status of the render. One of: "draft", "ready", "processing", "encoding", "complete", "failed", "deleted".

data object

An object containing the personalised data for this render.

output object

If status is complete, the outputted .mp4 file urls will be available. Returns "poster", "low", "medium", "high" & "master"

• poster string URL to a poster image.

• low string URL to a low-quality mp4 file.

• medium string URL to a medium-quality mp4 file.

• high string URL to a high-quality mp4 file.

• master string URL to the original high-quality mov prores file.

List Renders

GET /renders

Returns an array of the render object.

Read Render

GET /renders/:id

Returns the render object.

Create Render

POST /renders/

Request Body

{
	"project": "a909371f-af62-413a-92ba-f96d1c0e84e7",
	"account": "00460b3b-7cb7-4ef0-a567-df594a8f807e",
	"data": {
		"color": "#ff0000",
		"mainText": "Hello World"
	}
}

project uuid required

The id of the project you want to render against.

account uuid required

The id of the account you want to associate the render with.

data object required

The personalised data to replace in the template.

Response

Returns the render object.

Update Render

PATCH /render/:id

Request Body

{
	"title": "My New Render Title"
}

title string

The new title of the render.

Templates

The Template Object

{
	"id": "47658da2-32a0-4741-8dd8-56159e13ee7f",
	"date_created": "2022-10-28T10:11:48.974Z",
	"description": "<p>This is a description</p>",
	"playback_id": "ADeY00fm2UAOXoIjffVto9QI8IgsV2BER8Yzcf01799tY",
	"poster": null,
	"slug": "product-sale",
	"status": "published",
	"title": "Product Sale"
}

id uuid

Primary key of the template.

date_created string

Timestamp of when the template was created.

description string

HTML description of the template.

playback_id string

uuid of the video preview.

poster string

URL to the poster of the template

title string

The title of the template.

List Templates

GET /templates

Returns an array of the template object.

Read Template

GET /templates/:id

Returns the template object.

Errors