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:
| Method | Use |
|---|---|
GET | Retrieve or list data. |
POST | Submit data to create a resource or initiate an action. |
PUT | Update a resource or perform an action on an existing resource. |
DELETE | Delete 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/jsonCheck 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 class | Meaning |
|---|---|
2xx | Vitesse successfully received and processed the API request. |
4xx | Vitesse could not process the request because of its data, authentication, permissions or the current state of a resource. |
5xx | Vitesse 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.
Updated about 1 month ago