Build on Drellia with the REST API.

Authentication

Every endpoint, except the health check, needs an API key. Send the key in the x-api-key header. The API also accepts the same key as a bearer token in the Authorization header.

curl https://api.drellia.com/v1/agents \
  -H "x-api-key: $DRELLIA_API_KEY"

The Drellia team issues the API key for your organization. To get one, ask your account manager or write to support@drellia.com. One key works for Audit and for Voice.

The key is a secret. Keep it on your server. Do not put it in a URL, a log, source control or browser code. Drellia shows the key only when it issues or rotates it.

A request with no key, or with a key that is not valid, gets HTTP 401.

Base URL

https://api.drellia.com/v1

Send all requests over HTTPS to the production server. Every endpoint path starts with the version prefix /v1. The health check is at /health, with no prefix and no key.

Request and response bodies are JSON. Timestamps are ISO 8601 strings in UTC. The exception is originalDateTime, a Unix time in milliseconds that comes from your own system.

Quickstart: audit a chat transcript

These steps send one conversation for audit. You need an API key, an employee who is in a department, and a customer. Create them in the app or with the Employees and Customers endpoints.

1. 1

   Check that the API is up

   The health check needs no key.

   curl Copy

   curl https://api.drellia.com/health

2. 2

   Find the provider

   Each conversation comes through a provider, for example your chat channel. Copy the id of the provider.

   curl Copy

   curl https://api.drellia.com/v1/providers \
     -H "x-api-key: $DRELLIA_API_KEY"

3. 3

   Create the conversation

   Send the provider, the employee, the customer and the time of the conversation. The response has the conversation id and the status PENDING.

   curl Copy

   curl -X POST https://api.drellia.com/v1/conversations \
     -H "x-api-key: $DRELLIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "providerId": "<provider id>",
       "employeeId": "<employee id>",
       "customerId": "<customer id>",
       "originalDateTime": 1760000000000
     }'

4. 4

   Add the transcript

   Send all the messages in one request. Drellia evaluates the conversation after this call.

   curl Copy

   curl -X POST https://api.drellia.com/v1/conversations/<conversation id>/messages \
     -H "x-api-key: $DRELLIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "messages": [
         { "senderRole": "employee", "content": "Good morning, this is Ana from customer care.", "originalDateTime": 1760000000000 },
         { "senderRole": "customer", "content": "Hello, I want to check my last invoice.", "originalDateTime": 1760000004000 }
       ]
     }'

5. 5

   Read the status

   When the status is COMPLETED, the evaluation is ready in the Drellia app.

   curl Copy

   curl https://api.drellia.com/v1/conversations/<conversation id> \
     -H "x-api-key: $DRELLIA_API_KEY"
   # { "id": "…", "status": "COMPLETED", … }

Upload a call recording (JavaScript)

For a phone call, upload the audio instead of the messages. Ask for an upload URL, then send the file to that URL with an HTTP PUT. Drellia transcribes the audio and evaluates the call. A conversation can have one audio file.

import { readFile } from 'node:fs/promises';

const BASE_URL = 'https://api.drellia.com';
const headers = {
  'x-api-key': process.env.DRELLIA_API_KEY,
  'Content-Type': 'application/json',
};

// 1. Create the conversation.
const conversation = await fetch(`${BASE_URL}/v1/conversations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    providerId: '<provider id>',
    employeeId: '<employee id>',
    customerId: '<customer id>',
    originalDateTime: Date.now(),
  }),
}).then((r) => r.json());

// 2. Ask for an upload URL for the recording.
const audio = await readFile('call.mp3');
const { uploadUrl } = await fetch(
  `${BASE_URL}/v1/conversations/${conversation.id}/generate-upload-url`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      fileName: 'call.mp3',
      fileSize: audio.byteLength,
      contentType: 'audio/mpeg',
    }),
  },
).then((r) => r.json());

// 3. Upload the audio. Drellia transcribes and evaluates the call.
await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'audio/mpeg' },
  body: audio,
});

Start a voice-agent call (Python)

Start an outbound call with one of your agents. The agent path parameter accepts the agent id or its short key (AGT-…). Use the sessionId in the response to find the call later.

import os
import requests

BASE_URL = "https://api.drellia.com"
headers = {"x-api-key": os.environ["DRELLIA_API_KEY"]}

response = requests.post(
    f"{BASE_URL}/v1/agents/AGT-A1B2C3/calls",
    headers=headers,
    json={"phoneNumber": "+15555550100"},
    timeout=30,
)
response.raise_for_status()
call = response.json()
print(call["sessionId"], call["status"])

Conventions

List endpoints accept the page and pageSize query parameters. The first page is 1. The default page size is 50 and the maximum is 1,000. A list response has the shape { results, total, page, pageSize }.

Every resource has an id, which is a UUID. Some resources also have a short entityKey, for example AGT-A1B2C3. Where a path accepts an entityKey, the reference says so.

An error response from the API has an HTTP status of 400 or higher and a JSON body with statusCode, message and error. For a validation error (HTTP 400), message is a list with one line for each field that is not valid. The API rejects a body that has a field it does not know. A successful delete returns HTTP 204 with no body. The rate-limit response (HTTP 403) comes from the network edge and does not have this body.

{
  "statusCode": 404,
  "message": "Conversation with ID 3f2b9c1e-8a4d-4f6b-9c2e-1d7a5b8e0f42 not found",
  "error": "Not Found"
}

The API accepts up to 2,000 requests in each 5-minute window from one IP address. Above that, it returns HTTP 403 until the window ends. Contact support if you need a higher limit.

Resources

• API reference Every endpoint, parameter and response, generated from the OpenAPI contract.
• Interactive reference open_in_new The reference served by the API itself, where you can try requests with your key.
• OpenAPI 3 contract (JSON) Download the contract to generate a client or import it into your API tool.
• Developer support Questions about API access or an integration? Write to support@drellia.com.