pr-162-feat-tagged-deployments.api-stag.veo.co
Open in
urlscan Pro
13.35.93.34
Public Scan
Submitted URL: https://pr-162-feat-tagged-deployments.api-stag.veo.co/
Effective URL: https://pr-162-feat-tagged-deployments.api-stag.veo.co/docs/reference
Submission: On March 22 via api from US — Scanned from US
Effective URL: https://pr-162-feat-tagged-deployments.api-stag.veo.co/docs/reference
Submission: On March 22 via api from US — Scanned from US
Form analysis 0 forms found in the DOM
Text Content
ReDoc requires Javascript to function. Please enable it to browse the
documentation.
* Introduction
* Environments
* Get Started
* Explore the Veo API
* Register an API Client
* OAuth2.0
* Authentication
* Veo Authentication Service
* Initiate the Auth Flow
* Handle the Redirect
* Request Access Tokens
* Refresh the Session
* Logout
* Pushed Authorization Requests
* Security Configuration
* API Design Principles
* API Operations
* Data Types
* Identifiers
* Explicit null values and additionalProperties
* X-Request-Id Headers
* RFC Conformity
* API Errors
* 401 - Unauthorized
* 404 - Not Found
* 422 - Unprocessable Entity
* 500 - Internal Server Error
* 🚀 Upcoming APIs
* get[WIP] List Recordings
* get[WIP] List Clubs
* Clubs
* getGet Club
* get[WIP] List Clubs
* Matches
* getGet Match
* Recordings
* getGet Recording
* get[WIP] List Recordings
API docs by Redocly
VEO API (0.1.DEV1+G74B0CA5)
Reference Docs Explorer Terms of Service
View OAS Download JSON Download YAML
INTRODUCTION
Welcome to the Veo API reference documentation!
This page documents API functionality offered by Veo to support integrations
with the Veo Platform and should be used as primary reference for details
regarding the exact functionality and configuration of the Veo API. The intended
audience of this document is primarily developers that are looking to integrate
with the Veo Platform.
> For questions, comments, or feedback please get in touch with the API Team!
ENVIRONMENTS
The Veo API is available in three distinct flavors. Integration & exploration
typically starts in our sandbox environment, which runs the latest API version
against upstream test systems. Access to "next" and production environments is
restricted and requires a fully-functional sandbox integration that has been
approved by the Veo API Team. Test data and login users are provided upon
request.
Environment API URL Auth Service Intended use Production api.veo.co auth.veo.co
Production applications. Pre-prod next.api.veo.co auth.veo.co Test & validate
upcoming Veo API functionality. Sandbox sandbox.api.veo.co auth-dev.veo.co Demo
environment for testing, exploration & onboarding.
GET STARTED
EXPLORE THE VEO API
The easiest way to start tinkering with the Veo API is by logging into the
interactive Explorer, which is an adaption of Swagger UI with a pre-configured
authentication flow enabling login of Veo users (much like an actual
integration).
The Explorer runs against both sandbox and production backends and is useful for
debugging as well. If you have access to user credentials, follow these steps to
log into Veo API:
1. Pick the right environment:
* Sandbox Explorer - recommended, request a test user via our support inbox.
* Production Explorer - only log in here if you know what you are doing!
2. Click the "Authorize" button on the top-right, or any of the "lock" symbols
shown on the individual operations (which will pre-select the required
security scopes automatically).
3. Leave the pre-filled authorization configuration as-is and click
"Authorize".
4. A login window appears. Enter your credentials and accept the consent screen
showing the access scope that will be granted to the Explorer (should be:
api).
5. You are now logged in. Close the authorization popup in Swagger and start
making requests.
Congratulations, you are now using the Veo API!
Note: For demonstration purposes, the API will always requests user consent at
login. For actual integrations, this consent screen will only be shown upon
first login (or again if the user revokes access afterwards).
Note: The Explorer uses a public authentication client with access tokens that
are valid for 1 hour. Credentials are stored on the client side to keep your
session alive even if you close the browser, but Swagger does not currently
support automatic token refreshing. If you are logged-in but receive a 401
Unauthorized response, re-connect the session by logging in again.
REGISTER AN API CLIENT
> Onboarding form for API clients
All API clients are administered by the API Team and need to be requested by
following the steps laid out in the above form. Client configuration is only
valid for the environment that the client is created in. All client applications
are reviewed by the API Team to validated the requested configuration (such as
auth flows, redirect URLs, access to production, etc).
Note: The above form can also be used to update an existing API client. To keep
an accurate record of prevalent client configurations, we require all consumers
to request changes/updates via this form.
OAUTH2.0
Once the request for an API client has been approved, a client_id (and
client_secret for private clients) will be shared with the requestor, alongside
related configuration data. You can now set up the authentication flow for your
OAuth2.0 client!
This is in most cases however easier said then done, not in the least because
authentication errors tend to be opaque for security purposes.
Veo's authentication service is based on web standards and supports
out-of-the-box operation with (most) authentication clients. The easiest (and
typically the safest) way to get started is by using an off-the-shelf
OAuth2.0-compliant client.
Generally speaking, OAuth2.0 clients will perform the following tasks: construct
the authentication url, handle the redirect from the auth service, process the
response to obtain an access (and optional refresh token), and refreshing the
session when access tokens reach expiry. Each step is explained in the
Authentication section below.
AUTHENTICATION
VEO AUTHENTICATION SERVICE
The Veo API is secured by OAuth 2.0 access tokens issued by a OIDC-compliant
authentication service following current best practices, which can be
automatically discovered via below URLs:
Environment Discovery URL Production
https://auth.veo.co/.well-known/openid-configuration Sandbox
https://auth-dev.veo.co/.well-known/openid-configuration
INITIATE THE AUTH FLOW
To kick off the Authorization Code Flow, below URL should be composed based off
the client's configuration and must be rendered in a web browser so the end-user
can log in. Depending on the exact client configuration, specific query
parameters values need to be provided. When login is successful (or if an error
occurs), the user will be redirected to the redirect_uri with either an
authorization code or an error parameter value.
Note: Private clients that have been configured for offline_access need to
request refresh tokens by including this value in the scope parameter and
forcing login consent via prompt=consent.
Query Parameter Description Value Required client_id Identifier of the API
client. Registered API client identifier Yes redirect_uri Post-login redirect
location. (one of the) Registered redirect URL(s) Yes response_type Auth
response type. code Yes code_challenge_method PKCE code challenge method. S256
Yes code_challenge PKCE code challenge. Randomly generated code challenge Yes
resource Base URL of Veo API. Veo API URL Yes response_mode Auth response mode.
Recommended: public: fragment, private: form_post. fragment, form_post, or query
Yes scope Requested authorization scopes. offline_access for refresh tokens
only. api, offline_access api prompt Login prompt preference, required to be
consent to request refresh tokens. consent No state Recommended: state returned
upon redirect, can either be random and/or encoded information. Random data
and/or encoded state No
Note: Below example URLs exclude ampersand "&" separators for query and
url-encoded form parameters for readability.
https://auth.veo.co/oidc/auth? # auth service login URL
client_id={{client_id}} # client identifier received following registration
redirect_uri=https://example.com # one of the registered redirect URLs for this client
scope=api # "api offline_access" for refresh tokens
response_type=code # must be "code"
response_mode=fragment # recommended: "fragment" or "form_post"
code_challenge_method=S256 # must be "S256"
code_challenge={{code_challenge}} # generated PKCE code challenge
state={{state_value}} # state, can include useful information
resource=https://api.veo.co # required resource, must be the base URL of the Veo API
prompt=consent # only for requesting refresh tokens via "offline_access"
HANDLE THE REDIRECT
Assuming the user entered valid credentials and granted the requested scopes to
the application, the browser will be redirected to the requested redirect_uri.
If the user is already logged in (to a Veo platform), the authentication service
will immediately send the user back to the app through Single Sign-On (SSO).
This redirect can for example take the following form:
https://example.com? # redirect URI
code={{some_random_auth_code}} # authorization_code value
state={{state_value}} # state echoed from the originating request
iss=https://auth.veo.co # issuer of the authorization code (origin)
In case an error occurs, no auth code is returned and instead an error and
error_description parameter are provided. In the below example the required
response_type parameter was missing from the authentication request:
https://example.com? # redirect URI
error=invalid_request # error & description of the problem
error_description=missing required parameter 'response_type'
state={{state_value}} # state echoed from the originating request
iss=https://auth.veo.co # issuer of the error (origin)
REQUEST ACCESS TOKENS
Now that the client received the authorization_code, tokens can be requested
with a POST request to the /oidc/token endpoint of the authentication service.
The content type should be: application/x-www-form-urlencoded and include the
following parameters:
grant_type="authorization_code" # must be "authorization_code"
code={{authorization_code_value}} # "code" parameter value received through redirect
redirect_uri=https://example.com # redirect URL that the auth code was received on
code_verifier={{code_verifier}} # PKCE code verifier (see table above)
resource=https://api.veo.co # target resource (same as in authentication request)
Note: For public clients: the authorization code grant is sender-constrained and
can only be exercised from pre-configured origins to prevent credentials from
being used across different websites.
Note: For private clients, the above POST request can only be accepted if the
client is authenticated with the service through Client Authentication, i.e. a
Basic HTTP authentication header should be present in the request formatted as:
Authorization: base_64_encode({{client_id}}:{{client_secret}})
When the grant is validated by the authentication service, a 200 OK response is
returned with the below JSON payload. In case a private client adds the
offline_access scope in the authentication request (and prompt=consent to force
the end-user to acknowledge this), the response will also include a refresh
token.
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3d[...]",
"expires_in": 3600,
"refresh_token": "83TJTUnZeI[...]", // if offline_access is requested
"scope": "api",
"token_type": "Bearer"
}
Note: Access and refresh tokens are sensitive information and should be handled
with due care. Make sure these secrets do not leak from application memory via
logs, requests to external systems, or other mechanism that could expose these
values in plain-text.
REFRESH THE SESSION
As the above response example shows, access tokens have a restricted lifetime
(typically 1 hour), and will be rejected by Veo API with a 401 Unauthorized
error as soon as they expire. The API client is required to keep the
authentication session alive and obtain a fresh access token before the current
one expires in one of two ways depending on the type of client:
* Public clients should periodically re-run the authentication flow, which
leverages session cookies controlled by the authentication service and
immediately redirects back to the application. This operation is typically
performed in the background to keep the session alive for as long as the end
user is logged into the application.
* Private clients configured with refresh tokens can exercise it via a POST
request to the /oidc/token endpoint using client authentication (same as the
initial token request) and the following form-encoded payload:
grant_type=refresh_token
refresh_token=83TJTUnZeI[...]
LOGOUT
When the end-user disconnects from the application, the API client is expected
to properly end the session by removing access and refresh tokens from memory
and terminating the SSO session by sending the user to the /oidc/session/end
endpoint in the authentication service. When the end-user confirms logout
through the prompt, the session with the auth service is ended and the user is
redirected back to the provided post_logout_redirect_uri. For example:
https://auth.veo.co/oidc/session/end? # auth service logout URL
client_id={{client_id}} # client identifier
post_logout_redirect_uri=https://example.com # redirect URLs
PUSHED AUTHORIZATION REQUESTS
To enhance security of the auth request constructed above, the Veo
authentication service provides support for Pushed Authorization Requests, which
effectively replace the initial GET request to the /oidc/auth endpoint by a POST
request to the /oidc/request endpoint with query parameters sent via the payload
as application/x-www-form-urlencoded data. The authentication service uses
pre-configured CORS origins or Client Authentication to validate the
authenticity of the auth request before rendering a login page.
Note: An additional benefit of using pushed requests is pre-validation of auth
request parameters. The below POST request would be rejected by the
authentication service if it includes malformed data, before the user sees a
login screen. This allows for easier debugging of the required auth
configuration as well as a more graceful error-handling scenario (because the
user won't leave the application before the auth request is validated).
To perform a pushed authorization request, send the below
application/x-www-form-urlencoded data (which are the same parameters in the
above GET request) via a POST to /oidc/request. Private clients should provide a
Basic authorization header, public clients can only interact with the
authentication service from known origins.
client_id={{client_id}}
redirect_uri=https://example.com
scope=api
response_type=code
response_mode=fragment
code_challenge_method=S256
code_challenge={{code_challenge}}
state={{state_value}}
resource=https://api.veo.co
A successful response will include two fields:
{
"expires_in": 60,
"request_uri": "urn:ietf:params:oauth:request_uri:reD4T6z[...]"
}
To render a login window, construct the below authentication request and ensure
the user is sent to this location within the indicated timeout (typically 60
seconds).
https://auth.veo.co/oidc/auth?
client_id={{client_id}}
request_uri={{request_uri_value}}
The login flow will continue as normal and redirect the user back to the API
application with a authorization code when authentication is successful.
SECURITY CONFIGURATION
Client applications are administered by the Veo API team and are configured as
follows:
* Clients must use Authorization Code Flow + Proof Key for Code Exchange (PKCE)
with code challenge method SHA-256.
* Clients must use grant type: authorization_code or refresh_token. The
implicit grant type is not supported.
* Clients must use response type: code, issued via response modes: form_post,
fragment, or query. Response mode fragment is recommended for (single-page)
web applications to prevent authorization codes from leaking to backend
servers. form_post is recommended for private clients.
* Clients are recommended to use OAuth 2.0 Pushed Authorization Requests for
enhanced security.
* Clients must request scope api to access Veo API resources.
* Clients should support session logout via /session/end, optionally with a
redirect for optimal user experience.
* For public clients authenticating Veo users:
* The subject of the authentication request must be a Veo end user.
* All requests to the authentication service are sender-constrained and must
include an Origin header that is in a pre-configured allowlist of known
origins for the client.
* For private clients:
* The subject of the authentication request may be a Veo end user or may be a
dedicated service user provided by the API team separately.
* Client Authentication using a client secret must be provided for all
requests to the authentication service.
* The offline_access scope must be configured for the client if refresh
tokens are required, and the the authentication request must include query
parameter prompt=consent to receive a refresh_token grant.
* To prevent private client credentials being used for public applications,
the Origin header must not be set on requests to the authentication
service.
Note: Access tokens are formatted as JSON Web Tokens containing the claims
granted to the client application. Client applications may validate access
tokens by retrieving the JSON Web Key Set located at the authentication
service's discovery url /oidc/jwks using the iss (issuer) claim in the token as
host. OAuth2.0 client libraries that implement JWTs typically support signature
validation out of the box. See JWT.io for an example - Veo API access tokens
parsed by jwt.io should show a "Signature Verified" badge at the bottom of the
page.
API DESIGN PRINCIPLES
API OPERATIONS
Every operation exposed by the Veo API is either a GET operation (read) or a
POST operation (write). Every write operation is identified by a separate path,
which specifies the intended state change (and possible side effects). By using
only GET and POST methods, the Veo API is able to go beyond standard HTTP-based
semantics and more closely follow the intended modeling of the Veo Platform
domain.
Method Operation HTTP Verb Example Get Retrieve a single entity, typically by
its identifier. GET GET /recordings/{recording-id} List Retrieve a list of
entities of the same type. GET GET /recordings?club={club-id} Create
Instantiates a new entity. POST POST /recordings/{recording-id}/create-clip
Update/Delete Changes the value or state of an existing entity. POST POST
/recordings/{recording-id}/remove-clip
DATA TYPES
The Veo API uses the following data types:
Data Type Definition Format Example Reference Timestamp UTC timestamp with
millisecond precision. YYYY-MM-DDTHH:mm:ss.sssZ "2024-01-19T12:15:55.126Z"
RFC-3339 Duration Span of time expressed in milliseconds. Protobuf Duration JSON
representation "4140.552s" Duration
IDENTIFIERS
Entities in the Veo API are uniquely identified globally unique opaque
identifiers, similar to UUIDs.
EXPLICIT NULL VALUES AND ADDITIONALPROPERTIES
All schemas exposed by the Veo API include additionalProperties: false to
indicate that the specified properties of the schema in question fully
encapsulate the entity model. No unspecified properties will be returned by the
API. To facilitate nullable fields, this specification uses a type array with
"null" literals to indicate optionality, which is new in OAS 3.1.0 (see Swap
nullable for type arrays). In practice, this means that:
* All specified properties should always be returned by the API, regardless of
their value (i.e. static properties). The schema is an exact representation
of the response returned by the API.
* Properties that can be null are explicitly denoted as such, and can be
returned as "field": null.
X-REQUEST-ID HEADERS
Veo API supports the optional (unofficial) HTTP header X-Request-Id for tracing
purposes. API clients can use this header to identify individual API
interactions and correlate request and response data in client-side logs. The
value of this header is truncated to 64 characters, logged by the API to support
correlation between client and server-side logs, and echoed back to the client
in response headers. If an error is returned, the value is also set in the
response payload (field: x_request_id). Clients are recommended to use a
high-entropy unique identifier such as a UUID or ULID to identify requests. In
addition, a hint of the originating application (and its version) can be added
to further aid with debugging. For example:
X-Request-Id: my-app/v1.2.41/01HSE25FFZHH1NY3EE7DCNEHJ8
RFC CONFORMITY
The Veo API is designed to adhere strictly to web best practices and standards.
The below non-exhaustive list of IETF RFCs, Drafts and other (web) standards and
improvement proposals are observed and (partially) implemented by the Veo API
and auxillary services such as the authentication provider:
AUTHENTICATION & AUTHORIZATION
* OpenID Connect Core 1.0
* OpenID Connect Discovery 1.0
* RFC-6749 - The OAuth 2.0 Authorization Framework
* RFC-7519 - JSON Web Token (JWT)
* RFC-9126 - OAuth 2.0 Pushed Authorization Requests
* OAuth 2.0 Security Best Current Practice
API DESIGN
* RFC-7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
* RFC-4918 - HTTP Extensions for Web Distributed Authoring and Versioning
(WebDAV)
* RFC-8259 - The JavaScript Object Notation (JSON) Data Interchange Format
* RFC-7807 - Problem Details for HTTP APIs
* RFC-3339 - Date and Time on the Internet: Timestamps
OTHER
* AIP-122 - Resource names
* AIP-136 - Custom methods
* AIP-145 - Ranges
* X-Request-Id
API ERRORS
The Veo API aims to provide in-depth error details in accordance with RFC-7807 -
Problem Details for HTTP APIs when failures are observed. An error response can
be identified by its unique media type (response header Content-Type:
application/problem+json) and contains additional information about the issue in
the response body.
Every error is assigned a unique type, which is a direct link to the API
documentation with further information about the issue and instructions on how
to resolve it (see errors listed below). Clients are recommended to use all the
provided information in the error response and the documentation to attempt to
resolve the issue.
To assist with debugging (especially in distributed, highly-scalable systems)
clients are recommended to use the X-Request-Id header to identify the
originating request on the client side. If an error occurs, the API echoes the
header value in the x_request_id field in the error response. See X-Request-Id
Headers.
401 - UNAUTHORIZED
A 401 Unauthorized error response indicates an issue with request authentication
and is returned for one or more reasons:
* Authentication failed because the Authorization header is missing from the
request, or the header was improperly formatted (expected: Bearer
{{access_token}}). Confirm the access token is correctly set on the request.
* Authentication failed because the access token has expired (see example
response below). Refresh the access token before it expires (typical lifetime
is 1 hour). The access token exp claim can be verified by the client to
confirm the expiry of the access token.
* Authorization failed because the access token does not contain the required
scope(s) that the requested operation specifies. Confirm the scopes required
for the operation and ensure to request these scopes when authorizing users.
* Authentication failed for other reasons (bad access token signature,
incorrect claims, etc). No additional details are provided in these cases for
security purposes.
Example of a 401 Unauthorized response body:
{
"status": 401,
"reason": "Unauthorized",
"type": "https://api.veo.co/docs/reference#section/API-Errors/401-Unauthorized-Error",
"title": "Unauthorized Error",
"detail": "Authentication failed, see 'context' for more information.",
"context": "Access token expired at 2024-02-24T09:17:14.000Z (122 seconds ago).",
"request_url": "https://api.veo.co/bad-request-url",
"x_request_id": "my-unique-request-id",
"trace_id": "Root=1-65d9bd3c-3bd466443505178258fb6781",
"timestamp":"2024-02-29T11:32:40.568Z"
}
404 - NOT FOUND
A 404 Not Found error response indicates that the requested resource could not
be found, or the requesting user does not have access to retrieve the resource.
Confirm whether:
* The request parameters are provided correctly and point at an existing
resource.
* The requesting User is configured with the appropriate permissions to
retrieve the requested resource.
Example of a 404 Not Found response body:
{
"status": 404,
"reason": "Not Found",
"type": "https://api.veo.co/docs/reference#section/API-Errors/404-Not-Found-Error",
"title": "Not Found Error",
"detail": "The requested resource could not be found or the requesting User does not have access to this resource.",
"context": null,
"request_url": "https://api.veo.co/bad-request-url",
"x_request_id": "my-unique-request-id",
"trace_id": "Root=1-65d9bd3c-3bd466443505178258fb6781",
"timestamp":"2024-02-29T11:32:40.568Z"
}
422 - UNPROCESSABLE ENTITY
A 422 Unprocessable Entity error response indicates that the received request is
well-formed, but contains one or more issues with the semantics of the provided
data. The API validates all incoming data (request path, query, and body
parameters) and will raise this error if one or more parts of the request cannot
be processed accordingly.
In case this error is returned, the response body will include detailed guidance
with instructions on how to resolve the issue. In the below example for
instance, the request path parameter recording__id triggered a string_too_short
validation error because the provided string ("short-string") does not meet the
specified requirements ("min_length": 30).
Example of a 422 Unprocessable Entity response body:
{
"status": 422,
"reason": "Unprocessable Entity",
"type": "https://api.veo.co/docs/reference#section/API-Errors/422-Unprocessable-Entity",
"title": "Request Validation Error",
"detail": "One or more request parameters failed to validate, see 'context' for more information.",
"context": [
{
"error_type": "string_too_short",
"location": [
"path",
"recording_id",
"constrained-str"
],
"message": "String should have at least 30 characters",
"input": "short-string",
"error_context": {
"min_length": 30
}
}
],
"request_url": "https://api.veo.co/bad-request-url",
"x_request_id": "my-unique-request-id",
"trace_id": "Root=1-65d9bd3c-3bd466443505178258fb6781",
"timestamp":"2024-02-29T11:32:40.568Z"
}
500 - INTERNAL SERVER ERROR
In case the API encounters an internal error that it cannot recover from, the
server will return a 500 Internal Server Error response. If this error is
observed (and persists) make sure to reach out to the Veo API team and include
the details of the response body so our team of highly-trained monkeys can
resolve the issue as fast as possible.
Example of a 500 Internal Server Error response body:
{
"status": 500,
"reason": "Internal Server Error",
"type": "https://api.veo.co/docs/reference#section/API-Errors/500-Internal-Server-Error",
"title": "Internal Server Error",
"detail": "Oops! We scored an own goal. The server failed and a team of highly-trained monkeys are investigating. If this error persists, please contact the API team and make sure to include this error response in your message!",
"context": null,
"request_url": "https://api.veo.co/bad-request-url",
"x_request_id": "my-unique-request-id",
"trace_id": "Root=1-65d9bd3c-3bd466443505178258fb6781",
"timestamp":"2024-02-29T11:32:40.568Z"
}
🚀 UPCOMING APIS
[WIP] LIST RECORDINGS
get/recordings
https://pr-162-feat-tagged-deployments.api-stag.veo.co/recordings
Retrieve one or more Recording entities by their identifier, associated Club
entities, or a time interval during which the Recording took place. Filter
criteria are added as AND operations in the construction of the query if more
than one is provided. If no filter criteria are provided, all Recordings that
the User has access to are returned. The requesting User must have (at least)
view permissions on the Recording entity in order to retrieve it. An empty array
is returned in the response if the requested entity does not exist, none of the
filter criteria return any matches, or the User does not have access to the
Recording entity.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
QUERY PARAMETERS
recording
Array of strings <recording-id> (Recording ID Filter) [ items <recording-id > ]
Examples:
recording=ef03d67b-1395-409e-b64c-abb06470508d&recording=f90096bd-4985-4321-8e87-6732ceb7ba6c
Filter Recordings by identifier. Multiple identifiers can be provided by
repeating the query parameter.
club
Array of strings <club-id> (Club ID Filter) [ items <club-id > ]
Examples:
club=f37f3f29-38fa-4ec2-b7fe-9eafdd909e86&club=beb0a71d-ee8b-4eb9-af6c-fb2261a8ae2c
Filter Recordings by associated Club entities. Multiple identifiers can be
provided by repeating the query parameter.
start_timeline
Timestamp (UTC) (string) or Start Timeline (null) (Start Timeline)
Matches Recording timelines that intersect/overlap with this timeline. Required
if end_timeline is provided.
end_timeline
Timestamp (UTC) (string) or End Timeline (null) (End Timeline)
Matches Recording timelines that intersect/overlap with this timeline. Required
if start_timeline is provided.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
items
required
Array of objects (Items)
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "items": [
* {
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "timeline": {
* "start": "2024-01-19T12:15:55.126Z",
* "end": "2024-01-19T12:15:55.126Z"
},
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
],
* "clubs": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
],
* "matches": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
],
* "followcam": {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
]
},
* "panorama": {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
]
},
* "thumbnails": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
],
* "clips": [
* {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
],
* "end_offset": "4140.552s"
}
]
}
]
}
[WIP] LIST CLUBS
get/clubs
https://pr-162-feat-tagged-deployments.api-stag.veo.co/clubs
Retrieve one or more Club entities by their identifier, associated Club
entities, or a time interval during which the Club took place. Filter criteria
are added as AND operations in the construction of the query if more than one is
provided. If no filter criteria are provided, all Clubs that the User has access
to are returned. The requesting User must have (at least) view permissions on
the Club entity in order to retrieve it. An empty array is returned in the
response if the requested entity does not exist, none of the filter criteria
return any matches, or the User does not have access to the Club entity.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
QUERY PARAMETERS
club
Array of strings <club-id> (Club ID Filter) [ items <club-id > ]
Examples:
club=7A614C22-14D2-47D9-B9F6-AAF55E70AE16&club=E1D25E0B-0259-40D9-89F5-82C836F4138D
Filter Clubs by identifier. Multiple identifiers can be provided by repeating
the query parameter.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
items
required
Array of objects (Items)
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "items": [
* {
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "name": "Spring Training 1",
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
]
}
]
}
CLUBS
GET CLUB
get/clubs/{id}
https://pr-162-feat-tagged-deployments.api-stag.veo.co/clubs/{id}
Retrieve a club entity by its identifier. The requesting User must have (at
least) view permissions on the club entity in order to retrieve it. A 404 Not
Found error is returned if the requested entity does not exist or the User does
not have access.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
PATH PARAMETERS
id
required
string <club-id> (Id)
Examples: 4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8
Opaque string uniquely identifying a Club.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
id
required
string <club-id> (Club ID)
Examples: "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
Opaque string uniquely identifying a Club.
name
required
string (Name) [ 1 .. 100 ] characters
Examples: "Spring Training 1"
Human-readable, language independent string for display.
links
required
Array of objects (Links)
Collection of related URLs
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "name": "Spring Training 1",
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
]
}
[WIP] LIST CLUBS
get/clubs
https://pr-162-feat-tagged-deployments.api-stag.veo.co/clubs
Retrieve one or more Club entities by their identifier, associated Club
entities, or a time interval during which the Club took place. Filter criteria
are added as AND operations in the construction of the query if more than one is
provided. If no filter criteria are provided, all Clubs that the User has access
to are returned. The requesting User must have (at least) view permissions on
the Club entity in order to retrieve it. An empty array is returned in the
response if the requested entity does not exist, none of the filter criteria
return any matches, or the User does not have access to the Club entity.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
QUERY PARAMETERS
club
Array of strings <club-id> (Club ID Filter) [ items <club-id > ]
Examples:
club=7A614C22-14D2-47D9-B9F6-AAF55E70AE16&club=E1D25E0B-0259-40D9-89F5-82C836F4138D
Filter Clubs by identifier. Multiple identifiers can be provided by repeating
the query parameter.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
items
required
Array of objects (Items)
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "items": [
* {
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "name": "Spring Training 1",
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
]
}
]
}
MATCHES
GET MATCH
get/matches/{id}
https://pr-162-feat-tagged-deployments.api-stag.veo.co/matches/{id}
Retrieve a Match entity by its identifier. The requesting User must have (at
least) view permissions on the Match entity in order to retrieve it. A 404 Not
Found error is returned if the requested entity does not exist or the User does
not have access.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
PATH PARAMETERS
id
required
string <match-id> (Id)
Examples: 4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8
Opaque string uniquely identifying a Match.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
id
required
string <match-id> (Match ID)
Examples: "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
Opaque string uniquely identifying a Match.
timeline
required
object (Interval)
title
required
string (Title) [ 1 .. 100 ] characters
Examples: "Spring Training 1"
Human-readable, language independent string for display.
links
required
Array of objects (Links)
Collection of related URLs
recordings
required
Array of strings <recording-id> (Recordings) [ items <recording-id > ]
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "timeline": {
* "start": "2024-01-19T12:15:55.126Z",
* "end": "2024-01-19T12:15:55.126Z"
},
* "title": "Spring Training 1",
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
],
* "recordings": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
]
}
RECORDINGS
GET RECORDING
get/recordings/{id}
https://pr-162-feat-tagged-deployments.api-stag.veo.co/recordings/{id}
Retrieve a Recording entity by its identifier. The requesting User must have (at
least) view permissions on the Recording entity in order to retrieve it. A 404
Not Found error is returned if the requested entity does not exist or the User
does not have access.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
PATH PARAMETERS
id
required
string <recording-id> (Id)
Examples: 4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8
Opaque string uniquely identifying a Recording.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
id
required
string <recording-id> (Recording ID)
Examples: "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
Opaque string uniquely identifying a Recording.
timeline
required
object (Interval)
links
required
Array of objects (Links)
Collection of related URLs
clubs
required
Array of strings <club-id> (Clubs) [ items <club-id > ]
The related Clubs this Recording is shared with.
matches
required
Array of strings <match-id> (Matches) [ items <match-id > ]
The related Matches that include this Recording.
followcam
required
FollowCam (object) or null
A render with a virtual camera that follows the action.
panorama
required
Panorama (object) or null
The stationary render of the full view.
thumbnails
required
Array of objects (Thumbnails)
Thumbnail images in order of display preference.
clips
required
Array of objects (Clips)
Unordered clips of the source video with followcam or custom camera directions.
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "timeline": {
* "start": "2024-01-19T12:15:55.126Z",
* "end": "2024-01-19T12:15:55.126Z"
},
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
],
* "clubs": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
],
* "matches": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
],
* "followcam": {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
]
},
* "panorama": {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
]
},
* "thumbnails": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
],
* "clips": [
* {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
],
* "end_offset": "4140.552s"
}
]
}
[WIP] LIST RECORDINGS
get/recordings
https://pr-162-feat-tagged-deployments.api-stag.veo.co/recordings
Retrieve one or more Recording entities by their identifier, associated Club
entities, or a time interval during which the Recording took place. Filter
criteria are added as AND operations in the construction of the query if more
than one is provided. If no filter criteria are provided, all Recordings that
the User has access to are returned. The requesting User must have (at least)
view permissions on the Recording entity in order to retrieve it. An empty array
is returned in the response if the requested entity does not exist, none of the
filter criteria return any matches, or the User does not have access to the
Recording entity.
AUTHORIZATIONS:
OAuth2: Veo-OAuth2
QUERY PARAMETERS
recording
Array of strings <recording-id> (Recording ID Filter) [ items <recording-id > ]
Examples:
recording=ef03d67b-1395-409e-b64c-abb06470508d&recording=f90096bd-4985-4321-8e87-6732ceb7ba6c
Filter Recordings by identifier. Multiple identifiers can be provided by
repeating the query parameter.
club
Array of strings <club-id> (Club ID Filter) [ items <club-id > ]
Examples:
club=f37f3f29-38fa-4ec2-b7fe-9eafdd909e86&club=beb0a71d-ee8b-4eb9-af6c-fb2261a8ae2c
Filter Recordings by associated Club entities. Multiple identifiers can be
provided by repeating the query parameter.
start_timeline
Timestamp (UTC) (string) or Start Timeline (null) (Start Timeline)
Matches Recording timelines that intersect/overlap with this timeline. Required
if end_timeline is provided.
end_timeline
Timestamp (UTC) (string) or End Timeline (null) (End Timeline)
Matches Recording timelines that intersect/overlap with this timeline. Required
if start_timeline is provided.
RESPONSES
200
Successful Response
RESPONSE SCHEMA: APPLICATION/JSON
items
required
Array of objects (Items)
422
Validation Error
RESPONSE SAMPLES
* 200
* 422
Content type
application/json
Copy
Expand all Collapse all
{
* "items": [
* {
* "id": "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8",
* "timeline": {
* "start": "2024-01-19T12:15:55.126Z",
* "end": "2024-01-19T12:15:55.126Z"
},
* "links": [
* {
* "rel": "self",
* "href": "http://example.com"
}
],
* "clubs": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
],
* "matches": [
* "4AAAF6DC-00AD-4B35-B8A8-7A1AE265C7E8"
],
* "followcam": {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
]
},
* "panorama": {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
]
},
* "thumbnails": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
],
* "clips": [
* {
* "start_offset": "4140.552s",
* "links": [
* {
* "rel": "stream",
* "type": "video/mp4",
* "href": "http://example.com"
}
],
* "end_offset": "4140.552s"
}
]
}
]
}