> ## Documentation Index > Fetch the complete documentation index at: https://developers.vidbeo.com/llms.txt > Use this file to discover all available pages before exploring further. # Get started > Use our Video API to handle your video storage, transcoding and delivery. ## Structure Video API requests are made to a URI that follows this basic structure: `https://api.vidbeo.com/v2/[resource]/[parameters]` ## HTTP methods Each API request uses one of the following HTTP methods: | Method | Action | | ------ | ----------------------------------------------------------------------------------------------------------- | | GET | Used to **get** data about resources | | POST | Used to **create** a new resource | | PATCH | Used to **update** a resource. Any top-level attributes not included in your request will be left unchanged | | DELETE | Used to **delete** a resource | ## HTTP response codes We will generally use the standard [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) when returning responses so that your application knows what has happened: | Code | Meaning | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | The request was successful | | 400 | The request was invalid. Please check that you are including *all* required fields and that each value is the correct type | | 401 | The request could not be authorised. If you get this response code, please check that you are sending a valid API key | | 403 | The request is forbidden. The API key used is either invalid or does not permit that action on that resource | | 404 | The requested endpoint or resource could not be found. If you get this response code when trying to access an individual object, it has likely been deleted | | 429 | Too many requests have been made. You may have hit our rate-limit or our system is under load. Please wait for a short period of time before making another request | | 500 | There is a temporary problem with the API which resulted in an error | | 503 | There is a temporary problem with the API meaning it is currently unavailable | ## Authorization To make any request you will need an API key. To get one you will need: * An account with us to manage your billing. You can sign up using our dashboard: [https://dash.vidbeo.com/signup](https://dash.vidbeo.com/signup). * The Video API to be enabled for your account. Please get in touch. * The role of **owner** (the first user in any account always has this role). On our dashboard, the *API keys* page is within the *More* menu. A key is only shown once, so make a note of it and keep it secret. Your API key should be treated just like a password. That API key should be passed in a header like this: ```shell theme={null} curl \ -H "Authorization: Bearer YOUR-API-KEY" \ "https://api.vidbeo.com/v2/videos" ``` You should get a JSON response object back, with HTTP status code 200 (which means success). It will not actually contain any videos if you have not uploaded any yet. But this just tests everything is working: ```json theme={null} { "success": true, "result": [], "links": null, "errors": [] } ``` On the other hand if your API key is *not* valid, you should get an error response back (with an equivalent error HTTP status code, like 401 or 403). For example: ```json theme={null} { "success": false, "result": null, "links": null, "errors": [ { "message": "Invalid key value" } ] } ``` In our examples we will use the command-line tool `curl` as that makes it easy to illustrate how the requests are structured. However you will likely use a HTTP request library in your chosen language to do the same thing. For example PHP's [Guzzle](https://github.com/guzzle/guzzle) or NodeJS's [Got](https://github.com/sindresorhus/got). ## Error messages When errors occur, the HTTP status code will indicate the problem (for example a *400* code generally means there was a problem with the data sent). In the response object we will set *success* as *false* and should include at least one object in the errors array: ```json theme={null} { "success": false, "result": null, "links": null, "errors": [ { "message": "Unexpected field sent in request body" } ] } ``` ## CORS Our video API does not support client-side Cross Origin Resource Sharing (CORS). It must be used server-side. ## Date format Whenever our API returns a time, it will be formatted accordingly to the internationally-agreed standard known as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `2022-01-01T12:00:00.000Z` Dates passed to the API as part of your request need to also follow this format. For example: `2022-01-01` ## Performance Most data does not change very often so it makes sense to remember (at least for a short time) what our API responds with. This avoids having to repeatedly make the same request for the same data. Saving the API response in a temporary cache within your application not only reduces the chances of hitting our rate-limits but also makes your application faster since it can proceed without having to wait for our response. Naturally, please check the response and for a 2xx status code to check you are not accidentally caching an error. ## Passing parameters Some requests support being passed parameters. For example to paginate the returned data. For **GET** requests, these parameters should be part of the URL and sent [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding): `https://api.vidbeo.com/v2/resource/method?parameter1=value1¶meter2=value2` For **POST**, **PATCH** and **DELETE** requests, parameters should be passed within the body of the request (as JSON). Make sure to send the correct headers: `Content-Type: application/json` `Accept: application/json` ## Pagination If a large number of items need to be returned, to reduce bandwidth the API may only return a subset of the available results. Each subset is returned in a *page*. If there are more items in the result set than would fit within the page, multiple pages will need to be requested to return the entire result set. The pagination values are passed in the URL's query string. Endpoints that support pagination generally expect these two variables: | Variable | Type | Description | | -------- | ------ | -------------------------------------------------------------------------------------- | | limit | Int | The number to return per page | | cursor | String | A long string of characters which tells our system where to start the next requst from | You may have seen cursor-based pagination before, such as in the [Slack API](https://slack.engineering/evolving-api-pagination-at-slack/). It is more efficient than an offset-based approach. You can initially send a `limit`. For example `?limit=5`. And then **if** the response contains a `links` object which has a `next` key, *that's* the URL to use for your *next* API request to get the *next* page of results. That link will include a *cursor*. For example it may end like: `...?limit=5&cursor=a-long-value`. There are two different ways you can check to see if another request for another page **needs** to be made: **1)** You can count the number of results. If you requested a limit of 10 items and only 5 have been returned clearly there won't be another page of results following that one. **2)** You can check whether the response contains a *links* object that contains a *next* key. The exception in both these cases is when the number of results happens to match the number requested per page. For example if you ask for a limit of 10 items per page, and 10 are returned, there is not enough information to know whether there is an 11th item and so whether there is another page of results. Therefore the **links.next** URL may be built, in case. Upon requesting that next URL, it is at *that* point that you will know (since its *result* array will be empty). ## Rate-limiting We currently impose a limit on the number of requests that can be made to the API over a period of time. Further requests will be denied and will return with a HTTP status code of **429**. The limit varies per endpoint. As long as you follow best practices when making API requests, such as caching the responses where possible, this should not cause any problems for your application. If you find you are hitting these limits, and caching (see above) does not solve the issue, please get in touch. ## Updates We are constantly improving the platform. API changes are a key part of this. For example we may return *extra* data in a response, such as an additional key:value pair, or change the order elements appear. We will try to notify you of any changes so that you can decide what action, if any, to take.