# API Introduction

### Overview

The **Pristo API** allows external systems to securely integrate with Pristo in order to manage contacts, send events, and synchronize operational and customer-related data.

The API is designed using a **RESTful, design-first approach**, with predictable resource-oriented URLs, standard HTTP methods, and structured JSON payloads.\
All endpoints are documented and versioned to ensure backward compatibility and safe evolution over time.

This documentation describes **Pristo API V1**, which is intended for production integrations.

###

### API Base URL & Versioning

All API requests are made against a versioned base URL:

```
https://api.pristo.example.com/v1
```

* Versioning is handled via the URL path (`/v1`)
* Breaking changes will be introduced only in new major versions
* Minor, backward-compatible enhancements may be added within the same version

### Authentication

The Pristo API uses **API Key authentication**.

#### How Authentication Works

* Each request must include a valid API key
* The API key identifies the client system and controls access permissions
* Requests without a valid API key will be rejected

#### Authentication Header

Include the API key in every request header:

```
X-API-Key: YOUR_API_KEY
```

#### Security Notes

* API keys should be kept secret and never exposed in client-side code
* Rotate API keys periodically according to your security policy
* Requests over HTTP are not supported — HTTPS is required

###

### Obtaining an API Key

Follow these steps to generate your unique key:

1\. Click on your **Profile** icon in the top right corner.

2\. Select **Account Settings** from the dropdown menu.

<div align="left"><figure><img src="https://1897479074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgKjZGUaiXhnKBdODwHHP%2Fuploads%2Fx5qrQtLaowy5rSnefkaI%2Fimage.png?alt=media&#x26;token=a6260fac-2143-463b-82cc-3ed26c0ba7a1" alt=""><figcaption></figcaption></figure></div>

3\. Navigate to the **API Keys** tab and click the "**+Add**" button.

<figure><img src="https://1897479074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgKjZGUaiXhnKBdODwHHP%2Fuploads%2FfAKCphkIK3Mlsf5k4fdi%2Fimage.png?alt=media&#x26;token=953ed112-7dce-4725-a204-8a28973f77c1" alt=""><figcaption></figcaption></figure>

4. Enter a descriptive name for the key so you can easily identify it later.
5. **Copy** the new key immediately. Store it securely, as it will not be displayed again.

{% hint style="info" %}
Your API key will only be displayed once. You will not be able to view it again after closing the window.
{% endhint %}

###

### Request & Response Format

#### Content Type

All requests and responses use JSON:

```
Content-Type: application/json
Accept: application/json
```

#### Date & Time Format

All timestamps use **ISO 8601** format in UTC:

```
YYYY-MM-DDTHH:mm:ssZ
```

Example:

```
2026-02-04T13:25:00Z
```