API conventions

The Vitesse API uses HTTPS and exchanges data in JSON format.

💡

For conventions covering dates, times, currencies and other values, see Data formats.

Send requests over HTTPS

Send all API requests over HTTPS.

Use the complete URL provided in the API Guide for the relevant endpoint and environment. Use an endpoint path only with the host shown for that endpoint; do not append it to a different host.

Use HTTP methods

The Vitesse API uses standard HTTP methods:

MethodUse
GETRetrieve or list data.
POSTSubmit data to create a resource or initiate an action.
PUTUpdate a resource or perform an action on an existing resource.
DELETEDelete a resource where the endpoint supports deletion.

Check the API Reference for the method and behaviour of each endpoint.

Authenticate requests

Include a valid access token in the Authorization header using the bearer authentication scheme:

Authorization: Bearer <access-token>

For more information, see Authentication​.

Send JSON request bodies

When a request includes a body, send valid JSON and set the Content-Type header:

Content-Type: application/json

Check the API Reference for the property names, data types and permitted values that the endpoint accepts.

Interpret responses

Vitesse uses HTTP status codes to indicate the outcome of a request:

Status code classMeaning
2xxVitesse successfully received and processed the API request.
4xxVitesse could not process the request because of its data, authentication, permissions or the current state of a resource.
5xxVitesse encountered an error while processing the request.

Vitesse returns JSON when a response includes a body. Some successful requests return a response without a body.

A successful response does not always confirm that asynchronous processing has completed. For example, a response can confirm that Vitesse created a payment without confirming that the payment succeeded. When Vitesse continues processing asynchronously, follow the relevant API guide to check the resource status or subscribe to webhook events.

Individual endpoints can return different status codes and response bodies. Check the API Reference and ensure that your application handles every documented response.

Handle errors

Endpoints can return different error response formats. For response formats, HTTP status codes, common errors and recovery guidance, see Error responses.

Use the API Guide and API reference

Start with Welcome to the Vitesse API to find guidance for the task you want to complete.

The API Guide explains:

  • When and why to use an endpoint
  • The complete endpoint URL
  • The required OAuth scope and identity client role
  • Any prerequisites
  • Request and response examples
  • Task-specific guidance

Use the Vitesse API reference for the complete technical contract of each endpoint, including:

  • Required and optional parameters
  • Request and response schemas
  • Additional headers
  • Validation rules
  • Supported status codes
  • Example payloads

When an API guide or API Reference entry specifies requirements that are more specific than these conventions, follow those requirements.