Delivr Public API — Overview

1. Introduction

The Public API provides a robust and secure interface for managing applications, users, enterprises, organizations, projects, and tracking pixels.

To access protected endpoints you must obtain a JWT token and use valid client credentials. In addition, specific endpoints require extra scope headers (e.g., enterprise_id, organization_id, and project_id).

Production API URL: https://api.delivr.ai/public/core Staging API URL: https://api-staging.delivr.ai/public/core

1.1 Entity Correlation

In our system, different names are used in the UI and the API for the same underlying entities. Use the mapping below:

Notes

• Partner (UI) corresponds to Enterprise (API), reflecting a more formal designation in the API.
• Organization is used consistently across both UI and API.
• Workspace (UI) is equivalent to Project (API), emphasizing the functional role of this entity in the API.

2. Authentication & Authorization

The Public API uses a combination of client credentials and JWT tokens to protect endpoints. You must first create an application to obtain client credentials. These credentials are required for all protected requests, with a few exceptions.

2.1 Client Credentials

When you create an app, you can receive two credentials by calling /api/app/retrieve:

• X-Delivr-Client-ID: a3f7b1e2-9c44-4d1f-8e21-5b2f0c7d9a11
• X-Delivr-Client-Secret: Esdw0E-1b2c3d4e5f6a7b8c9d0e1f2-NAZV4

Include these headers in all requests to protected endpoints (enterprise, organization, project, user, pixel, and certain app endpoints), except:

• Health checks: /, /health
• Auth issue token endpoint: /auth/issue
• App creation endpoint: /api/app/create
• App retrieval endpoint: /api/app/retrieve

Header example

X-Delivr-Client-ID: a3f7b1e2-9c44-4d1f-8e21-5b2f0c7d9a11
X-Delivr-Client-Secret: Esdw0E-1b2c3d4e5f6a7b8c9d0e1f2-NAZV4

2.2 Additional Protected Endpoints

After obtaining your client credentials, certain endpoints also require a valid JWT token (obtained from /auth/issue).

Combined headers (example)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature
X-Delivr-Client-ID: a3f7b1e2-9c44-4d1f-8e21-5b2f0c7d9a11
X-Delivr-Client-Secret: Esdw0E-1b2c3d4e5f6a7b8c9d0e1f2-NAZV4

2.3 Steps to obtain a JWT Token

Please note that the JWT token for the Public API is different from the JWT token for Resolutions&Events and Data API

1. Sign In: use your existing credentials on the dashboard:
   • Staging: https://staging.delivr.ai
   • Production: https://app-v2.delivr.ai
2. Issue Token: make a request to the /auth/issue endpoint to obtain a JWT token.
3. Include Token in Requests: add the JWT token to the Authorization header for each request to protected endpoints.

2.4 Global Request Headers

For all protected API calls (under /api/), include:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature
X-Delivr-Client-ID: a3f7b1e2-9c44-4d1f-8e21-5b2f0c7d9a11
X-Delivr-Client-Secret: Esdw0E-1b2c3d4e5f6a7b8c9d0e1f2-NAZV4

Plus, where applicable (scope headers):

enterprise_id: 7b6c2a11-5c44-4f3b-98d1-2e1f0c7d9a55
organization_id: 5e2a9c44-b1e2-4d1f-8e21-7b6c0c7d9a33
project_id: 9c44a3f7-b1e2-4d1f-8e21-5b2f0c7d9a77

To build your own hierarchy of enterprises, organizations and projects, you can use /api/user/overview, where you pass only JWT and obtain all structure levels.

3. Getting Started

Properly setting up your development environment is crucial for seamless integration with the Public API. The steps below will help you configure your environment and start making API requests quickly.

3.1 Creating an App

Before creating an app, obtain a JWT via /auth/issue using your email and password from:

• Staging: https://staging.delivr.ai
• Production: https://app-v2.delivr.ai

The app creation endpoint does not require client credentials, but does require JWT. Upon successful creation, you can later retrieve your client_id and client_secret from the app retrieval endpoint.

3.2 Retrieving Client Credentials

Use /api/app/retrieve (secured by JWT) to obtain the client_id and client_secret associated with your newly created app. With these credentials, you can make authenticated requests to other endpoints.

3.3 Setting up Your Environment

• Include X-Delivr-Client-ID and X-Delivr-Client-Secret headers in all requests to protected endpoints (except health, auth issue, and app create/retrieve).
• Obtain a JWT via /auth/issue and include Authorization: Bearer <token> for endpoints that require JWT in addition to client credentials.

4. API Endpoints - Overview

The Public API endpoints are grouped as follows:

• Health check (no auth required)
• Auth (no auth required)
• Enterprise management (requires JWT, client credentials, and enterprise_id header)
• Organization management (requires JWT, client credentials, and organization_id header)
• Project management (requires JWT, client credentials, and both organization_id and project_id headers)
• User management (requires JWT and client credentials; applicable across enterprise, organization, and project scopes)
• Pixel management (requires JWT, client credentials, and project_id header)

Every described endpoint below must include our staging or production API domain, based on your need.

• Production API domain: https://api.delivr.ai/public/core/
• Staging API domain: https://api-staging.delivr.ai/public/core/