PHP SDK

The official PHP SDK provides a convenient way to interact with the Datalumo API from any PHP application.

Requirements

• PHP 8.2 or later
• A Datalumo account with an API token

Installation

Install via Composer:

composer require datalumo/php-sdk

Initialisation

Create a client instance with your API token:

use Datalumo\PhpSdk\Datalumo;

$datalumo = new Datalumo('your-api-token');

You can find your API token in your organisation settings. If you're running a self-hosted instance, pass the base URL as the second argument:

$datalumo = new Datalumo('your-api-token', 'https://custom-instance.example.com');

Collections

List collections

$response = $datalumo->collections()->list();

foreach ($response->data as $collection) {
    echo $collection->name;
}

Filter by project or paginate:

$response = $datalumo->collections()->list(project: 'docs', page: 2);

if ($response->hasMorePages()) {
    // fetch next page
}

Create a collection

$collection = $datalumo->collections()->create('Support Articles');

// With a project
$collection = $datalumo->collections()->create('FAQ', project: 'website');

echo $collection->id; // UUID

Update a collection

$collection = $datalumo->collections()->update('collection-id', 'New Name');

Delete a collection

$datalumo->collections()->delete('collection-id');

Entries

Access entries through a collection ID:

$entries = $datalumo->entries('collection-id');

List entries

$response = $entries->list();
$response = $entries->list(page: 2);

Create an entry

$entry = $entries->create([
    'raw_text' => 'The content to index',
    'title' => 'My Entry',
    'meta' => ['author' => 'John', 'tags' => ['billing', 'refunds']],
    'source_url' => 'https://example.com/page',
    'source_type' => 'articles',
    'source_id' => '42',
]);

Only raw_text is required. All other fields are optional.

Upsert an entry

Create or update an entry matched by source_type and source_id. This is ideal for syncing content from an external system:

$entry = $entries->upsert([
    'raw_text' => 'Updated content',
    'title' => 'Updated title',
    'source_type' => 'articles',
    'source_id' => '42',
]);

Batch upsert

Create or update up to 50 entries in a single request:

$result = $entries->batchUpsert([
    ['raw_text' => 'First entry', 'source_type' => 'posts', 'source_id' => '1'],
    ['raw_text' => 'Second entry', 'source_type' => 'posts', 'source_id' => '2'],
    ['raw_text' => 'Third entry', 'source_type' => 'posts', 'source_id' => '3'],
]);

echo $result['created']; // 3
echo $result['updated']; // 0

Update an entry

$entry = $entries->update('entry-id', [
    'title' => 'Updated Title',
    'meta' => ['category' => 'updated'],
]);

Delete an entry

$entries->delete('entry-id');

Delete by source

Remove an entry by its source reference instead of its Datalumo ID:

$entries->deleteBySource('articles', '42');

Integrations

Integrations are the consumption layer in Datalumo. While collections and entries manage your data, integrations are how you search, summarise, and chat with that data. Each integration connects to one or more collections and can be configured with its own persona, instructions, and settings.

List integrations

$response = $datalumo->integrations()->list();

// Filter by type and/or project
$response = $datalumo->integrations()->list(type: 'chatbot', project: 'support');

Get an integration

$integration = $datalumo->integrations()->get('integration-id');

Create an integration

$integration = $datalumo->integrations()->create([
    'type' => 'chatbot',
    'name' => 'Support Bot',
    'collection_ids' => ['col-id-1', 'col-id-2'],
    'accent_color' => '#3b82f6',
    'allowed_domains' => ['example.com'],
    'welcome_message' => 'How can I help?',
    'persona' => 'friendly',
]);

See the API Reference for all available options per integration type.

Update an integration

$integration = $datalumo->integrations()->update('integration-id', [
    'name' => 'Updated Bot',
    'is_active' => false,
]);

Delete an integration

$datalumo->integrations()->delete('integration-id');

Record an event

Track user interactions with an integration:

$datalumo->integrations()->recordEvent('integration-id', [
    'event_type' => 'thumbs_up',  // 'click', 'thumbs_up', or 'thumbs_down'
    'meta' => ['url' => 'https://example.com/page'],
]);

Search

Search, summarise, and chat all go through an integration. This allows you to search across multiple collections at once and leverage integration-specific settings like persona and instructions.

Search an integration

$results = $datalumo->integrations()->search('integration-id', [
    'query' => 'how do refunds work',
]);

foreach ($results->data as $entry) {
    echo $entry->title;
    echo $entry->rawText;
}

echo $results->summarisable; // true if results are good for summarisation

You can adjust the similarity threshold, filter by metadata, and control pagination:

$results = $datalumo->integrations()->search('integration-id', [
    'query' => 'refund policy',
    'threshold' => 0.3,   // 0-1, default 0.4
    'meta' => ['category' => 'billing'],
    'per_page' => 10,
    'page' => 1,
]);

A lower threshold returns more results but may include less relevant matches.

Summarise

Get an AI-generated summary of matching results:

$summary = $datalumo->integrations()->summarise('integration-id', [
    'query' => 'explain your refund policy',
]);

echo $summary->summary;            // markdown summary
echo $summary->references;         // source references
echo $summary->data;               // matched entries
echo $summary->hasRelevantResults;  // whether relevant content was found

Control the output format and language:

$summary = $datalumo->integrations()->summarise('integration-id', [
    'query' => 'explain your refund policy',
    'format' => 'html',  // 'markdown' (default) or 'html'
    'locale' => 'nl',    // response language
]);

Chat

Have a conversation grounded in your integration's content:

$response = $datalumo->integrations()->chat('integration-id', [
    'message' => 'What is your refund policy?',
]);

echo $response->message;          // AI response
echo $response->conversationId;   // use to continue the conversation

Continue an existing conversation by passing the conversation_id:

$followUp = $datalumo->integrations()->chat('integration-id', [
    'message' => 'How long do I have?',
    'conversation_id' => $response->conversationId,
]);

Streaming

The summarise and chat endpoints support streaming via Server-Sent Events (SSE). Instead of waiting for the full response, you receive text chunks as they are generated.

Stream a chat response

$stream = $datalumo->integrations()->streamChat('integration-id', [
    'message' => 'What is your refund policy?',
]);

// Iterate over text chunks as they arrive
foreach ($stream->text() as $chunk) {
    echo $chunk; // "Refunds", " are", " available", ...
    flush();
}

Stream a summary

$stream = $datalumo->integrations()->streamSummarise('integration-id', [
    'query' => 'explain the refund policy',
]);

foreach ($stream->text() as $chunk) {
    echo $chunk;
    flush();
}

Get the full text at once

If you want streaming for the transport but still need the complete text at the end:

$stream = $datalumo->integrations()->streamChat('integration-id', [
    'message' => 'hello',
]);

$fullResponse = $stream->fullText();

Access all stream events

For full control, iterate over the raw StreamEvent objects:

$stream = $datalumo->integrations()->streamChat('integration-id', [
    'message' => 'hello',
]);

foreach ($stream as $event) {
    match (true) {
        $event->isTextDelta() => print($event->data),
        $event->isCitation() => handleCitation($event->citation()),
        $event->isError() => throw new Exception($event->data),
        $event->isStreamEnd() => break,
        default => null, // stream_start, text_start, text_end, etc.
    };
}

Each StreamEvent has a type, optional data, and the full raw array from the API.

Error handling

The SDK throws specific exceptions for different error types:

use Datalumo\PhpSdk\Exceptions\AuthenticationException;
use Datalumo\PhpSdk\Exceptions\ValidationException;
use Datalumo\PhpSdk\Exceptions\NotFoundException;
use Datalumo\PhpSdk\Exceptions\QuotaExceededException;
use Datalumo\PhpSdk\Exceptions\DatalumoException;

try {
    $datalumo->collections()->create('');
} catch (ValidationException $e) {
    $e->getMessage();  // "The name field is required."
    $e->errors();      // ['name' => ['The name field is required.']]
} catch (AuthenticationException $e) {
    // 401 Unauthenticated or 403 Forbidden
} catch (QuotaExceededException $e) {
    // 402 — usage quota exceeded
} catch (NotFoundException $e) {
    // 404 — resource not found
} catch (DatalumoException $e) {
    // any other API error (429, 500, etc.)
}

All exceptions extend DatalumoException and include the response body via $e->body.

Data objects

All API responses are returned as typed data objects with readonly properties:

Paginated responses also have a hasMorePages() helper method.