pr-111-feat-error-handling.api-stag.veo.co Open in urlscan Pro
18.238.55.35  Public Scan

Form analysis
0 forms found in the DOM

Text Content

ReDoc requires Javascript to function. Please enable it to browse the
documentation.
 * Introduction
 * API Design Principles
   * RFC Conformity
   * API Operations
   * Data Types
   * Identifiers
   * Explicit null values and additionalProperties
 * Authentication
   * Veo OpenID Connect (OIDC)
   * Security Configuration
   * OAuth 2.0 Scopes for Client Authorization
 * API Errors
   * 401 - Unauthorized
   * 404 - Not Found
   * 422 - Unprocessable Entity
   * 500 - Internal Server Error
 * Recordings
   * getGet Recording
   * get[WIP] List Recordings
 * 🚀 Upcoming APIs
   * get[WIP] List Recordings
 * getGet Protected Resource

API docs by Redocly





VEO API (0.1.DEV1+GFC5AC0D)




Reference Docs Explorer View OAS

Download JSON Download YAML


INTRODUCTION

Welcome to the Veo API reference documentation!


API DESIGN PRINCIPLES


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-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-136 - Custom Method Names
 * AIP-145 - Ranges


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.

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 by a 3-character lowercase
string hinting at the type of the entity, followed by an underscore '_' and a
uppercase ULID value (regex: ^[a-z]{3}_[A-Z0-9]{26}$).

Note: identifiers should be treated as opaque string values. The 3-letter hint
or the timestamp encoded in the ULID should not be used in-code. These purely
serve as hint to the developer to help understand the context when observing a
standalone identifier.


EXPLICIT NULL VALUES AND ADDITIONALPROPERTIES

All schemas in this specification 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 a
"null" literal, 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).
 * Properties that can be null are explicitly denoted as such. All other
   properties will always be returned and should always have a value assigned.


AUTHENTICATION


VEO OPENID CONNECT (OIDC)

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 Staging
https://auth-dev.veo.co/.well-known/openid-configuration


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.
 * Clients are recommended to use OAuth 2.0 Pushed Authorization Requests for
   enhanced security.
 * Clients may obtain user information via /me, validate access and refresh
   tokens via /token/introspection, and revoke access tokens via
   /token/revocation.
 * Clients should support session logout via /session/end, optionally with a
   redirect for optimal user experience.
 * Clients may request scope open_id and provide a nonce parameter to validate
   the received id_token if identity verification is required.
 * 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 must be provided for all requests to the
     authentication service.
   * The offline_access scope must be configured for the client, 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 opaque strings that do not encode any
information for security purposes. Clients can review token claims via the
/introspection endpoint if required.


OAUTH 2.0 SCOPES FOR CLIENT AUTHORIZATION

The Veo API uses OAuth 2.0 Access Token Scopes to control client access to
operations. Client-level access is evaluated separately from user authorization
and controls general permissions of the application. Scopes are formatted as a
unordered space-separated case-sensitive list of scope names, such as profile
email phone_number. Any scopes that are unrecognized or not configured on the
client are automatically ignored. The /token response includes a scope parameter
indicating the scopes that are granted to the client.


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. Clients are
recommended to use a high-entropy unique identifier such as a UUID or ULID to
identify requests. The response field x_request_id is limited to the first 50
characters provided in the header.


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"
}



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"
}



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 ("rec_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": "rec_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"
}



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"
}



RECORDINGS

Recordings form the core entity of the Veo Platform.


GET RECORDING

get/recordings/{recording_id}

Veo API Gateway

http://localhost:3000/recordings/{recording_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.

PATH PARAMETERS

recording_id
required
string <entity-id> (Recording Id) = 30 characters ^rec_[A-Z0-9]{26}$
Examples: rec_40X3EHMPG5YW3HMZZQ3F6APQPS

Opaque string uniquely identifying a Recording entity formatted as
<prefix>_<ULID>. Note: the prefix rec_ should only be used as hint to indicate
what entity this identifier points to and should not be consumed in-code.


RESPONSES

200

Successful Response

RESPONSE SCHEMA: APPLICATION/JSON

id
required
string <entity-id> (Recording ID)
Examples: "rec_40X3EHMPG5YW3HMZZQ3F6APQPS"

Opaque string uniquely identifying a Recording entity formatted as
<prefix>_<ULID>. Note: the prefix rec_ should only be used as hint to indicate
what entity this identifier points to and should not be consumed in-code.

start_time
required
string <date-time> (Timestamp (UTC)) = 24 characters
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$
Examples: "2024-01-19T12:15:55.126Z"

UTC timestamp with millisecond precision formatted as YYYY-MM-DDTHH:mm:ss.sssZ
conforming to RFC-3339.

end_time
required
Timestamp (UTC) (string) or End Time (null) (End Time)

_links
required
Array of objects ( Links)

renders
required
Array of objects (Renders)

clips
required
Array of objects (Clips)


422

Validation Error


RESPONSE SAMPLES

 * 200
 * 422

Content type
application/json
Copy
Expand all Collapse all
{
 * "id": "rec_40X3EHMPG5YW3HMZZQ3F6APQPS",
 * "start_time": "2024-01-19T12:15:55.126Z",
 * "end_time": "2024-01-19T12:15:55.126Z",
 * "_links": [
    * {
       * "href": "https://veo.co",
       * "rel": "self",
       * "id": "rec_40X3EHMPG5YW3HMZZQ3F6APQPS"
      
      }
   
   ],
 * "renders": [
    * {
       * "type": "followcam",
       * "_links": [
          * {
             * "href": "https://veo.co",
             * "rel": "source",
             * "type": "video/mp4"
            
            }
         
         ]
      
      }
   
   ],
 * "clips": [
    * {
       * "start_offset": "4140.552s",
       * "end_offset": "4140.552s",
       * "duration": "4140.552s",
       * "_links": [
          * {
             * "href": "https://veo.co",
             * "rel": "source",
             * "type": "video/mp4"
            
            }
         
         ]
      
      }
   
   ]

}



[WIP] LIST RECORDINGS

get/recordings/

Veo API Gateway

http://localhost:3000/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.

QUERY PARAMETERS

self
Array of Recording ID Filter (strings) or Recording ID Filter (null) (Recording
ID Filter)
Examples:
self=rec_01HQ89XNTBNABAF8JVHWK6F9SW&self=rec_01HQ89XNTBNABAF8JVHWK6F9SW

Filter Recordings by identifier. Multiple identifiers can be provided by
repeating the query parameter.

club
Array of Club ID Filter (strings) or Club ID Filter (null) (Club ID Filter)
Examples:
club=clb_01HQ89XNTBNABAF8JVHWK6F9SW&club=clb_01HQ89XNTBNABAF8JVHWK6F9SW

Filter Recordings by associated Club entities. Multiple identifiers can be
provided by repeating the query parameter.

overlap_start
string <date-time> (Overlap Start)
Default: "2000-01-01T00:00:00"

Recording time span within this start time

overlap_end
Timestamp (UTC) (string) or Overlap End (null) (Overlap End)

Recording UUIDtime span within this end time


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": "rec_40X3EHMPG5YW3HMZZQ3F6APQPS",
       * "start_time": "2024-01-19T12:15:55.126Z",
       * "end_time": "2024-01-19T12:15:55.126Z",
       * "_links": [
          * {
             * "href": "https://veo.co",
             * "rel": "self",
             * "id": "rec_40X3EHMPG5YW3HMZZQ3F6APQPS"
            
            }
         
         ],
       * "renders": [
          * {
             * "type": "followcam",
             * "_links": [
                * {
                   * "href": "https://veo.co",
                   * "rel": "source",
                   * "type": "video/mp4"
                  
                  }
               
               ]
            
            }
         
         ],
       * "clips": [
          * {
             * "start_offset": "4140.552s",
             * "end_offset": "4140.552s",
             * "duration": "4140.552s",
             * "_links": [
                * {
                   * "href": "https://veo.co",
                   * "rel": "source",
                   * "type": "video/mp4"
                  
                  }
               
               ]
            
            }
         
         ]
      
      }
   
   ]

}



🚀 UPCOMING APIS


[WIP] LIST RECORDINGS

get/recordings/

Veo API Gateway

http://localhost:3000/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.

QUERY PARAMETERS

self
Array of Recording ID Filter (strings) or Recording ID Filter (null) (Recording
ID Filter)
Examples:
self=rec_01HQ89XNTBNABAF8JVHWK6F9SW&self=rec_01HQ89XNTBNABAF8JVHWK6F9SW

Filter Recordings by identifier. Multiple identifiers can be provided by
repeating the query parameter.

club
Array of Club ID Filter (strings) or Club ID Filter (null) (Club ID Filter)
Examples:
club=clb_01HQ89XNTBNABAF8JVHWK6F9SW&club=clb_01HQ89XNTBNABAF8JVHWK6F9SW

Filter Recordings by associated Club entities. Multiple identifiers can be
provided by repeating the query parameter.

overlap_start
string <date-time> (Overlap Start)
Default: "2000-01-01T00:00:00"

Recording time span within this start time

overlap_end
Timestamp (UTC) (string) or Overlap End (null) (Overlap End)

Recording UUIDtime span within this end time


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": "rec_40X3EHMPG5YW3HMZZQ3F6APQPS",
       * "start_time": "2024-01-19T12:15:55.126Z",
       * "end_time": "2024-01-19T12:15:55.126Z",
       * "_links": [
          * {
             * "href": "https://veo.co",
             * "rel": "self",
             * "id": "rec_40X3EHMPG5YW3HMZZQ3F6APQPS"
            
            }
         
         ],
       * "renders": [
          * {
             * "type": "followcam",
             * "_links": [
                * {
                   * "href": "https://veo.co",
                   * "rel": "source",
                   * "type": "video/mp4"
                  
                  }
               
               ]
            
            }
         
         ],
       * "clips": [
          * {
             * "start_offset": "4140.552s",
             * "end_offset": "4140.552s",
             * "duration": "4140.552s",
             * "_links": [
                * {
                   * "href": "https://veo.co",
                   * "rel": "source",
                   * "type": "video/mp4"
                  
                  }
               
               ]
            
            }
         
         ]
      
      }
   
   ]

}



GET PROTECTED RESOURCE

get/protected_resource

Veo API Gateway

http://localhost:3000/protected_resource

AUTHORIZATIONS:

OpenID Connect: Veo Authentication Service


RESPONSES

200

Successful Response

RESPONSE SCHEMA: APPLICATION/JSON

access_token
required
string (Access Token)

jwt_claims
required
object (Jwt Claims)


401

Unauthorized

404

Not Found

422

Unprocessable Entity

500

Internal Server Error


RESPONSE SAMPLES

 * 200
 * 401
 * 404
 * 422
 * 500

Content type
application/json
Copy
Expand all Collapse all
{
 * "access_token": "string",
 * "jwt_claims": { }

}