VEO API

The VEO API gives you a wealth of tools to video tagging and AI analysis capability seamlessly integrated into to your own digital products.

Before you begin

Almost all of the endpoints in the VEO API require an authentication token. Find out more about authentication and authorization.

Swagger

The API has a full list of swagger documentation and this guide only highlights the most common scenarios. If you think something is missing from these docs and needs clarification beyond the swagger documentation then please get in touch.

Base URL

We offer environments for your production code and for your development needs. You'll need a seperate Client ID and secret for each of these environments:

• for Production use https://api.veo.co.uk/api as the base url for all calls.
• for development and testing use https://apiuat.veo.co.uk/api as the base url for all calls.

Bearer tokens

Once you've authenticated you'll be given a bearer token. Almost all API endpoints require this token to identify you and your rights.

The recommended way to make requests is by adding the bearer token to the header of the HTTP request as follows:

curl https://api.veo.co.uk/api/{your_chosen_endpoint} \
  -H "Authorization: Bearer {token}"

A good example of this is to get the transcript for an existing video in VEO which you would do as follows:

curl --location 'https://api.veo.co.uk/api/videos/{videoID}/transcript' \
--header 'Authorization: Bearer {token}'

Common patterns and practices

When working with the API we have a few common patterns and practices to try and keep your integration simple and consistent. It is important however to check the swagger documentation for the actions you want to perform because the common practice may differ from time to time.

Resource naming convention

Getting lists

Generally a resource is described in the plural form when retrieving a collection. For example, to get a list of videos you perform a GET request on the /videos endpoint or to get a list of users you would perform a GET request on the /users endpoint.

Lists generally contain a subset of the information available for the resource and to retrieve all of the information about a resource you would perform a GET request on the individual resource by id

Creating resources

When creating resources you would generally perform a POST on the plural form of a collection. For example to create a new portfolio you would perform a POST on the /portfolios endpoint.

Getting individual resources

To retrieve an individual resource you would normally perform this on the plural form of a resource followed by the id of the resource you want to retrieve. For example to retrieve portfolio ID 27 you would perform a GET request on /portfolios/27.

Sometimes this differs in the API and the request is performed as part of the query string. For example, to retrieve a user with an id of 27 you would perform a GET request against /user?id=27.

Deleting individual resources

To delete an individual resource you would normally perform this on the plural form of a resource followed by the id of the resource you want to delete. For example to delete portfolio ID 27 you would perform a DELETE request on /portfolios/27.

Sometimes this differs in the API and the request is performed as part of the query string. For example, to delete a user with an id of 27 you would perform a DELETE request against /user?id=27.

Updating individual resources

To update an individual resource you would normally perform this on the plural form of a resource followed by the id of the resource you want to update. For example to retrieve update ID 27 you would perform a PUT request on /portfolios/27.

Sometimes this differs in the API and the request is performed as part of the query string. For example, to update a user with an id of 27 you would perform a PUT request against /user?id=27.

Pagination

Many of the endpoints will include pagination in the results when retrieving lists. The default page size for most endpoints is 10.

Paginated requests generally will include the pagination options as the following query parameters:

• pageSize - The number of items you want to retrieve per page.
• pageNumber - The page of items you wish to retrieve.
• orderBy - The field to which you wish to order your results. These will be listed in the swagger docs.
• orderByDirection - A value of ASC to specify ascending order or DESC to specify descending order.

For example, to get the 20 most recent videos you would perform the following request:

curl --location 'videos/v3/get-all?pageSize=20&pageNumber=1&orderByDirection=DESC&orderBy=UPLOADEDSTAMP' \
--header 'Authorization: Bearer {token}'

The resulting JSON which is returned generally contains the following four properties:

• Items- the array of resources you requested.
• Page - the page number you requested.
• PageSize - the number of items you requested per page.
• TotalItemCount - The number of items in this response which will either equal the number of items you requested or be fewer where the request exhausted past the end of the page results.

An example response to the preceeding request would be as follows:

{
    "Items": [
        ``` omitted for brevity
    ],
    "Page": 1,
    "PageSize": 20,
    "TotalItemCount": 20
}

Status codes

The API will return status codes according to the use case but the most common are as follows:

Successful codes

• 200 - When requesting resources which you are allowed to retrieve, the response code will be 200 - OK and the resulting body will be the resource(s) you requested.
• 201 - When creating a resources which you are allowed to create, the response code will be 201 - Created.
• 202 - When updating a resources which you are allowed to update, the response code will be 202 - Updated.

Error responses

• 400 - When a request does not make sense to the API it will return a 400 - Bad request
• 401 - When you have requested a resource which does not belong to your organisation or you do not have the rights to retrieve, the API will return a 401 - Unauthorized
• 404 - When you have requested a resource which does exist, the API will return a 404 - Not found
• 500 - When an unknown error has occurred, the API will return a 500 - Internal server error