PHP SDK

Requirements

PHP 8.1 or higher
cURL extension
JSON extension

Installation

Install via Composer:

composer require skald/skald-php

Quick Start

<?php

require 'vendor/autoload.php';

use Skald\Skald;
use Skald\Types\MemoData;
use Skald\Types\UpdateMemoData;
use Skald\Types\SearchRequest;
use Skald\Types\SearchMethod;
use Skald\Types\ChatRequest;
use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Initialize the client
$skald = new Skald('sk_proj_your_api_key');

// Create a memo
$result = $skald->createMemo(new MemoData(
    title: 'Meeting Notes - Q1 Planning',
    content: 'Discussed quarterly goals, hiring plans, and budget allocation...',
    tags: ['meeting', 'planning', 'q1'],
    source: 'notion'
));

// Search for memos
$results = $skald->search(new SearchRequest(
    query: 'quarterly goals',
    searchMethod: SearchMethod::CHUNK_VECTOR_SEARCH,
    limit: 10,
    filters: [
        Filter::nativeField('tags', FilterOperator::IN, ['planning', 'q1'])
    ]
));

foreach ($results->results as $result) {
    echo "Title: {$result->title}\n";
    echo "Summary: {$result->summary}\n";
    echo "Relevance: {$result->distance}\n\n";
}

// Ask questions about your knowledge base
$response = $skald->chat(new ChatRequest(
    query: 'What are our main goals for Q1?'
));

echo $response->response; // "The main Q1 goals are..."

API Reference

Client Initialization

$skald = new Skald(string $apiKey, ?string $baseUrl = null);

$apiKey: Your Skald API key (required)
$baseUrl: Optional custom API base URL (defaults to https://api.useskald.com)

Creating Memos

$response = $skald->createMemo(MemoData $memoData): CreateMemoResponse;

Parameters:

new MemoData(
    title: string,              // Required - memo title (max 255 chars)
    content: string,            // Required - memo content
    metadata: ?array = null,    // Optional - custom JSON metadata
    reference_id: ?string = null, // Optional - external ID mapping
    tags: ?array = null,        // Optional - array of tags
    source: ?string = null      // Optional - source system (e.g., "notion")
);

Example:

$result = $skald->createMemo(new MemoData(
    title: 'Product Requirements',
    content: 'The new mobile app should support offline mode...',
    metadata: ['author' => 'John Doe', 'version' => '1.0'],
    tags: ['product', 'mobile', 'requirements'],
    source: 'confluence'
));

// Returns: CreateMemoResponse { ok: true }

Updating Memos

$response = $skald->updateMemo(
    string $memoId,
    UpdateMemoData $updateData,
    string $idType = 'memo_uuid'
): CreateMemoResponse;

Update an existing memo with partial or complete changes. All fields are optional - only include the fields you want to update. Important: When content is updated, the memo is automatically reprocessed by the API (summary, tags, and chunks are regenerated). Other field updates preserve existing processing results. Parameters:

$memoId (string): The memo UUID or client reference ID
$updateData (UpdateMemoData): The fields to update
$idType (string, optional): Type of identifier - 'memo_uuid' (default) or 'reference_id'

new UpdateMemoData(
    title: ?string = null,                  // Optional - memo title (max 255 chars)
    content: ?string = null,                // Optional - memo content (triggers reprocessing)
    metadata: ?array = null,                // Optional - custom JSON metadata
    client_reference_id: ?string = null,    // Optional - external ID mapping (max 255 chars)
    source: ?string = null,                 // Optional - source system (max 255 chars)
    expiration_date: ?string = null         // Optional - expiration date (ISO 8601 format)
);

Examples:

use Skald\Types\UpdateMemoData;

// Update by memo UUID (default)
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    title: 'Updated Title'
));

// Update by client reference ID
$skald->updateMemo('external-id-123', new UpdateMemoData(
    title: 'Updated via Reference ID'
), 'reference_id');

// Update content (triggers automatic reprocessing)
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    content: 'New content - this will regenerate summary, tags, and chunks'
));

// Update multiple fields
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    title: 'Updated Title',
    metadata: ['updated_at' => time(), 'editor' => 'Jane'],
    source: 'notion',
    expiration_date: '2025-12-31T23:59:59Z'
));

// Update metadata without triggering reprocessing
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    metadata: ['last_viewed' => time(), 'view_count' => 42]
));

Deleting Memos

$skald->deleteMemo(
    string $memoId,
    string $idType = 'memo_uuid'
): void;

Delete a memo and all its associated data (content, summary, tags, chunks). Parameters:

$memoId (string): The memo UUID or client reference ID
$idType (string, optional): Type of identifier - 'memo_uuid' (default) or 'reference_id'

Examples:

// Delete by memo UUID (default)
$skald->deleteMemo('memo-uuid-here');

// Delete by client reference ID
$skald->deleteMemo('external-id-123', 'reference_id');

Searching Memos

$response = $skald->search(SearchRequest $searchParams): SearchResponse;

Search Methods:

SearchMethod::CHUNK_VECTOR_SEARCH - Semantic search on memo chunks (returns distance scores 0-2)
SearchMethod::TITLE_CONTAINS - Case-insensitive substring match on titles
SearchMethod::TITLE_STARTSWITH - Case-insensitive prefix match on titles

Parameters:

new SearchRequest(
    query: string,                  // Required - search query
    searchMethod: SearchMethod,     // Required - search method
    limit: ?int = null,            // Optional - results limit (1-50, default 10)
    filters: ?array = null         // Optional - array of Filter objects
);

Example:

use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Basic search
$results = $skald->search(new SearchRequest(
    query: 'product requirements',
    searchMethod: SearchMethod::CHUNK_VECTOR_SEARCH,
    limit: 5
));

foreach ($results->results as $result) {
    echo "UUID: {$result->uuid}\n";
    echo "Title: {$result->title}\n";
    echo "Summary: {$result->summary}\n";
    echo "Snippet: {$result->content_snippet}\n";
    echo "Distance: {$result->distance}\n\n"; // Lower = more relevant
}

// Search with filters
$results = $skald->search(new SearchRequest(
    query: 'product requirements',
    searchMethod: SearchMethod::CHUNK_VECTOR_SEARCH,
    limit: 5,
    filters: [
        Filter::nativeField('tags', FilterOperator::IN, ['product', 'requirements']),
        Filter::nativeField('source', FilterOperator::EQ, 'confluence')
    ]
));

See Filters for advanced filtering options.

AI Chat (Non-Streaming)

$response = $skald->chat(ChatRequest $chatParams): ChatResponse;

Parameters:

new ChatRequest(
    query: string,              // Required - question to ask
    filters: ?array = null      // Optional - advanced filtering (see Filters)
);

Examples:

use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Basic chat
$response = $skald->chat(new ChatRequest(
    query: 'What are the key features of our mobile app?'
));

echo $response->response;
// Output: "The mobile app has several key features: 1. Offline mode
//          2. Push notifications 3. Biometric authentication"

// Chat with filters to narrow context
$response = $skald->chat(new ChatRequest(
    query: 'What are our Q1 goals?',
    filters: [
        Filter::nativeField('tags', FilterOperator::IN, ['q1', 'planning'])
    ]
));

See Filters for advanced filtering options.

AI Chat (Streaming)

$stream = $skald->streamedChat(ChatRequest $chatParams): Generator<ChatStreamEvent>;

Example:

$stream = $skald->streamedChat(new ChatRequest(
    query: 'Summarize our product roadmap'
));

foreach ($stream as $event) {
    if ($event->isToken()) {
        echo $event->content; // Print each token as it arrives
    } elseif ($event->isDone()) {
        echo "\nDone!\n";
        break;
    }
}

Document Generation (Non-Streaming)

$response = $skald->generateDoc(GenerateDocRequest $generateParams): GenerateDocResponse;

Parameters:

new GenerateDocRequest(
    prompt: string,             // Required - document generation prompt
    rules: ?string = null,      // Optional - style/format rules
    filters: ?array = null      // Optional - advanced filtering (see Filters)
);

Examples:

use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Basic document generation
$response = $skald->generateDoc(new GenerateDocRequest(
    prompt: 'Create a product requirements document for the mobile app',
    rules: 'Use formal business language. Include sections: Overview, Requirements, Timeline'
));

echo $response->response;
// Outputs a full document with inline citations

// Generate with filters to control context
$response = $skald->generateDoc(new GenerateDocRequest(
    prompt: 'Write a technical specification for our API',
    rules: 'Include Architecture, Endpoints, and Security sections',
    filters: [
        Filter::nativeField('source', FilterOperator::EQ, 'technical-docs')
    ]
));

See Filters for advanced filtering options.

Document Generation (Streaming)

$stream = $skald->streamedGenerateDoc(GenerateDocRequest $generateParams): Generator<GenerateDocStreamEvent>;

Example:

$stream = $skald->streamedGenerateDoc(new GenerateDocRequest(
    prompt: 'Write a technical specification for our API',
    rules: 'Include Architecture, Endpoints, and Security sections'
));

foreach ($stream as $event) {
    if ($event->isToken()) {
        echo $event->content;
    } elseif ($event->isDone()) {
        echo "\n[Generation complete]\n";
        break;
    }
}

Error Handling

All API errors throw Skald\Exceptions\SkaldException:

use Skald\Exceptions\SkaldException;

try {
    $result = $skald->createMemo(new MemoData(
        title: 'Test',
        content: 'Content'
    ));
} catch (SkaldException $e) {
    // Error format: "Skald API error (STATUS_CODE): ERROR_MESSAGE"
    echo "Error: " . $e->getMessage();
    echo "HTTP Status: " . $e->getCode();
}

Examples

See the examples/ directory on GitHub for complete working examples:

create_memo.php - Creating memos with various options
update_memo.php - Updating existing memos
delete_memo.php - Deleting memos by UUID or reference ID
search.php - All search methods with filters
chat.php - Non-streaming chat
chat_streaming.php - Streaming chat with real-time output
generate_doc.php - Document generation
generate_doc_streaming.php - Streaming document generation

Getting started

Self-host

SDKs

API Reference

Requirements

Installation

Quick Start

API Reference

Client Initialization

Creating Memos

Updating Memos

Deleting Memos

Searching Memos

AI Chat (Non-Streaming)

AI Chat (Streaming)

Document Generation (Non-Streaming)

Document Generation (Streaming)

Error Handling

Examples

Getting started

Self-host

SDKs

API Reference

Documentation Index

​Requirements

​Installation

​Quick Start

​API Reference

​Client Initialization

​Creating Memos

​Updating Memos

​Deleting Memos

​Searching Memos

​AI Chat (Non-Streaming)

​AI Chat (Streaming)

​Document Generation (Non-Streaming)

​Document Generation (Streaming)

​Error Handling

​Examples

Requirements

Installation

Quick Start

API Reference

Client Initialization

Creating Memos

Updating Memos

Deleting Memos

Searching Memos

AI Chat (Non-Streaming)

AI Chat (Streaming)

Document Generation (Non-Streaming)

Document Generation (Streaming)

Error Handling

Examples