PHPackages                             administrate/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. administrate/sdk

ActiveLibrary[API Development](/categories/api)

administrate/sdk
================

The official PHP SDK for the Administrate.dev REST API

v0.1.0(2mo ago)00MITPHPPHP ^8.1

Since Feb 19Pushed 2mo agoCompare

[ Source](https://github.com/administrate-dev/administrate-php-sdk)[ Packagist](https://packagist.org/packages/administrate/sdk)[ Docs](https://github.com/administrate-dev/administrate-php-sdk)[ RSS](/packages/administrate-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

Administrate PHP SDK
====================

[](#administrate-php-sdk)

The official PHP SDK for the [Administrate.dev](https://administrate.dev) REST API.

[Administrate.dev](https://administrate.dev) is AI Agency Management software. It is a monitoring and management platform for AI agencies running n8n and AI automation workflows across multiple clients. It provides a single dashboard to track every workflow, every client, every failure, and all LLM costs, so you can catch problems before clients do and prove the value of your automations.

**Key platform features:**

- **Multi-instance monitoring** -- See all n8n instances across every client in one place
- **Error tracking** -- Real-time failure detection with automatic error categorization
- **LLM cost tracking** -- Connect OpenAI, Anthropic, Azure, and OpenRouter accounts to attribute costs to specific clients
- **Workflow insights** -- Execution counts, success rates, and time-saved ROI reporting
- **Sync health** -- Know instantly when a data sync fails
- **Webhooks & API** -- Full programmatic access for custom integrations

Installation
------------

[](#installation)

Install via Composer:

```
composer require administrate/sdk
```

Requires PHP 8.1+.

Quick start
-----------

[](#quick-start)

```
use Administrate\Administrate;

$client = new Administrate(apiKey: 'sk_live_...');

// Get account info
$account = $client->account->get();
echo "{$account->name} ({$account->plan})";

// List all clients with auto-pagination
foreach ($client->clients->list() as $c) {
    echo "{$c->name} ({$c->code})\n";
}

// Check for failed executions across all instances
foreach ($client->executions->list(errorsOnly: true) as $execution) {
    echo "{$execution->workflow_name}: {$execution->error_category}\n";
}

// Get LLM cost summary
$costs = $client->llmCosts->summary();
echo "Total: $" . number_format($costs->data->summary->total_cost_cents / 100, 2);
```

Configuration
-------------

[](#configuration)

```
use Administrate\Administrate;

$client = new Administrate(
    apiKey: 'sk_live_...',            // Required. Must start with "sk_live_"
    baseUrl: 'https://...',           // Default: "https://administrate.dev"
    timeout: 30,                      // Request timeout in seconds. Default: 30
    maxRetries: 3,                    // Retry attempts for failed requests. Default: 3
);
```

You can also pass any PSR-18 compatible HTTP client:

```
$client = new Administrate(
    apiKey: 'sk_live_...',
    client: $yourPsr18Client,
);
```

API reference
-------------

[](#api-reference)

All API keys are created in **Settings > Developers** within Administrate.dev. Tokens have three permission levels: `read`, `write`, and `full`.

### Account

[](#account)

```
// Get current token info and account summary
$me = $client->account->me();
echo "{$me->token->name} ({$me->token->permission})";
echo "{$me->account->name} ({$me->account->plan})";

// Get full account details
$account = $client->account->get();

// Update account settings
$account = $client->account->update(
    name: 'My Agency',
    billingEmail: 'billing@example.com',
    timezone: 'Australia/Brisbane',
);
```

### Clients

[](#clients)

Clients represent the companies you manage automations for.

```
// List all clients (auto-paginates)
foreach ($client->clients->list() as $c) {
    echo "{$c->name} ({$c->code})\n";
}

// Get a client (includes 7-day metrics)
$c = $client->clients->get('com_abc123');
echo "{$c->metrics->success_rate}% success, {$c->metrics->time_saved_minutes} min saved";

// Create a client
$c = $client->clients->create(
    name: 'Acme Corp',
    code: 'acme',
    contactEmail: 'ops@acme.com',
    timezone: 'America/New_York',
);

// Update a client
$c = $client->clients->update('com_abc123', notes: 'Enterprise tier');

// Delete a client (requires full permission)
$client->clients->delete('com_abc123');
```

### Instances

[](#instances)

Instances are n8n deployments connected to Administrate.

```
// List all instances
foreach ($client->instances->list() as $inst) {
    echo "{$inst->name} ({$inst->sync_status})\n";
}

// Filter by client or sync status
foreach ($client->instances->list(clientId: 'com_abc123', syncStatus: 'error') as $inst) {
    echo "{$inst->name}: {$inst->last_sync_error}\n";
}

// Get an instance (includes 7-day metrics)
$inst = $client->instances->get('n8n_abc123');
echo "{$inst->metrics->executions_count} executions, {$inst->metrics->success_rate}% success";

// Connect a new n8n instance
$inst = $client->instances->create(
    clientId: 'com_abc123',
    name: 'Production n8n',
    baseUrl: 'https://n8n.acme.com',
    apiKey: 'n8n_api_key_here',
);

// Trigger a sync
$client->instances->sync('n8n_abc123', syncType: 'all');

// Sync all instances at once
$client->instances->syncAll(syncType: 'workflows');

// Update an instance
$inst = $client->instances->update('n8n_abc123', name: 'Staging n8n');

// Delete an instance
$client->instances->delete('n8n_abc123');
```

### Workflows

[](#workflows)

```
// List workflows with filters
foreach ($client->workflows->list(clientId: 'com_abc123', active: true) as $wf) {
    echo "{$wf->name} (active: {$wf->is_active})\n";
}

// Search by name
foreach ($client->workflows->list(search: 'onboarding') as $wf) {
    echo $wf->name . "\n";
}

// Get a workflow (includes 7-day metrics)
$wf = $client->workflows->get('wfl_abc123');
echo "{$wf->metrics->success_rate}% success, {$wf->metrics->time_saved_minutes} min saved";

// Set time-saved estimates (for ROI reporting)
$wf = $client->workflows->update(
    'wfl_abc123',
    minutesSavedPerSuccess: 15,
    minutesSavedPerFailure: 5,
);
```

### Executions

[](#executions)

Executions are read-only records of workflow runs synced from n8n.

```
// List executions with filters
foreach ($client->executions->list(
    clientId: 'com_abc123',
    status: 'failed',
    startDate: '2025-01-01',
    endDate: '2025-01-31',
) as $ex) {
    echo "{$ex->workflow_name} - {$ex->status} ({$ex->duration_ms}ms)\n";
}

// Get only errors
foreach ($client->executions->list(errorsOnly: true) as $ex) {
    echo "{$ex->error_category}: {$ex->workflow_name}\n";
}

// Get execution details (includes error message and payload)
$ex = $client->executions->get('exe_abc123');
echo $ex->error_message;
```

### Sync runs

[](#sync-runs)

```
// List sync run history
foreach ($client->syncRuns->list(instanceId: 'n8n_abc123', status: 'failed') as $run) {
    echo "{$run->sync_type} - {$run->status} ({$run->duration_seconds}s)\n";
}

// Get a specific sync run
$run = $client->syncRuns->get('syn_abc123');

// Get sync health across all instances
foreach ($client->syncRuns->health() as $entry) {
    echo "{$entry->instance_name} ({$entry->sync_status})\n";
    echo "  Workflows last synced: {$entry->workflows->last_synced_at}\n";
    echo "  Executions last synced: {$entry->executions->last_synced_at}\n";
}
```

### Users

[](#users)

```
// List team members
foreach ($client->users->list() as $user) {
    echo "{$user->name} email}> ({$user->role})\n";
}

// Get a user
$user = $client->users->get('usr_abc123');

// Invite a new team member
$invitation = $client->users->invite(email: 'new@example.com', role: 'member');
echo $invitation->expires_at;

// Change a user's role
$user = $client->users->update('usr_abc123', role: 'admin');

// Remove a user
$client->users->delete('usr_abc123');
```

### Webhooks

[](#webhooks)

```
// List webhooks
foreach ($client->webhooks->list() as $wh) {
    echo "{$wh->url} - " . implode(', ', $wh->events) . " (enabled: {$wh->enabled})\n";
}

// Create a webhook
$wh = $client->webhooks->create(
    url: 'https://example.com/hook',
    events: ['execution.failed', 'sync.failed'],
    description: 'Slack failure alerts',
);
echo $wh->secret; // Save this -- used to verify webhook signatures

// Update a webhook
$wh = $client->webhooks->update('whk_abc123', enabled: false);

// Regenerate the signing secret (old secret becomes invalid immediately)
$wh = $client->webhooks->regenerateSecret('whk_abc123');
echo $wh->secret;

// Delete a webhook
$client->webhooks->delete('whk_abc123');
```

### API tokens

[](#api-tokens)

```
// List all tokens
foreach ($client->apiTokens->list() as $token) {
    echo "{$token->name} ({$token->permission}) - {$token->token_hint}\n";
}

// Create a token (the plain token is only returned once)
$token = $client->apiTokens->create(
    name: 'CI/CD Pipeline',
    permission: 'read',
    ipAllowlist: ['10.0.0.0/8'],
    expiresIn: '90_days',
);
echo $token->token; // sk_live_... -- save this immediately

// Update a token
$token = $client->apiTokens->update('tok_abc123', name: 'Updated Name');

// Revoke a token
$client->apiTokens->delete('tok_abc123');
```

### LLM providers

[](#llm-providers)

Connect your AI provider accounts to track costs.

```
// List providers
foreach ($client->llmProviders->list() as $provider) {
    echo "{$provider->name} ({$provider->provider_type}) - {$provider->sync_status}\n";
}

// Get a provider (includes 7-day metrics)
$provider = $client->llmProviders->get('llm_abc123');
echo "{$provider->metrics->total_cost_cents}c, {$provider->metrics->total_tokens} tokens";

// Connect a new provider
$provider = $client->llmProviders->create(
    name: 'OpenAI Production',
    providerType: 'openai',  // openai, anthropic, openrouter, or azure
    apiKey: 'sk-...',
    organizationId: 'org-...',
);

// Trigger a cost sync
$client->llmProviders->sync('llm_abc123');

// Update a provider
$provider = $client->llmProviders->update('llm_abc123', name: 'OpenAI Staging');

// Delete a provider
$client->llmProviders->delete('llm_abc123');
```

### LLM projects

[](#llm-projects)

Projects are discovered automatically when syncing a provider. Assign them to clients to attribute costs.

```
// List projects for a provider
foreach ($client->llmProjects->list('llm_abc123') as $project) {
    echo "{$project->name}: {$project->total_cost_cents}c ({$project->client_name})\n";
}

// Assign a project to a client
$project = $client->llmProjects->update(
    'llm_abc123', 'proj_456', clientId: 'com_abc123',
);
```

### LLM costs

[](#llm-costs)

```
// Get cost summary (defaults to last 7 days)
$costs = $client->llmCosts->summary();
echo "Total: $" . number_format($costs->data->summary->total_cost_cents / 100, 2) . "\n";
echo "Tokens: {$costs->data->summary->total_tokens}\n";

// Breakdown by provider
foreach ($costs->data->providers as $p) {
    echo "  {$p->name}: $" . number_format($p->cost_cents / 100, 2) . "\n";
}

// Breakdown by model
foreach ($costs->data->models as $m) {
    echo "  {$m->model}: $" . number_format($m->cost_cents / 100, 2) . "\n";
}

// Daily trend
foreach ($costs->data->daily as $day) {
    echo "  {$day->date}: $" . number_format($day->cost_cents / 100, 2) . "\n";
}

// Custom date range
$costs = $client->llmCosts->summary(
    startDate: '2025-01-01',
    endDate: '2025-01-31',
);

// Costs by client
foreach ($client->llmCosts->byClient()->data as $entry) {
    echo "{$entry->name}: $" . number_format($entry->cost_cents / 100, 2) . "\n";
}

// Costs by provider
foreach ($client->llmCosts->byProvider()->data as $entry) {
    echo "{$entry->name}: $" . number_format($entry->cost_cents / 100, 2) . "\n";
}
```

Pagination
----------

[](#pagination)

All `->list()` methods return an `IteratorAggregate` that handles pagination automatically. By default, the API returns 25 items per page (max 100).

```
// Auto-paginate through all results
foreach ($client->clients->list() as $c) {
    echo $c->name . "\n";
}

// Control page size
foreach ($client->clients->list(perPage: 100) as $c) {
    echo $c->name . "\n";
}

// Get a single page
$page = $client->clients->list(perPage: 10)->firstPage();
echo "{$page->meta->total} total, {$page->meta->total_pages} pages\n";
foreach ($page as $c) {
    echo $c->name . "\n";
}
```

Error handling
--------------

[](#error-handling)

The SDK raises typed exceptions for all API errors:

```
use Administrate\Administrate;
use Administrate\Exceptions\ApiException;
use Administrate\Exceptions\AuthenticationException;
use Administrate\Exceptions\NotFoundException;
use Administrate\Exceptions\RateLimitException;
use Administrate\Exceptions\ValidationException;

$client = new Administrate(apiKey: 'sk_live_...');

try {
    $c = $client->clients->get('com_nonexistent');
} catch (NotFoundException $e) {
    echo "Not found: {$e->getMessage()}";
} catch (AuthenticationException) {
    echo 'Invalid API key';
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->retryAfter}s";
} catch (ValidationException $e) {
    echo "Invalid params: " . json_encode($e->body);
} catch (ApiException $e) {
    echo "API error {$e->statusCode}: {$e->getMessage()}";
}
```

**Exception hierarchy:**

ExceptionStatus codeDescription`AdministrateException`--Base exception for all SDK errors`ApiException`Any non-2xxBase for all HTTP API errors`AuthenticationException`401Invalid or missing API key`PermissionDeniedException`403Insufficient token permissions`NotFoundException`404Resource does not exist`ValidationException`422Invalid request parameters`RateLimitException`429Rate limit exceeded (has `retryAfter`)`InternalServerException`5xxServer-side error`ConnectionException`--Failed to connect to the API`TimeoutException`--Request timed outAll `ApiException` subclasses expose `statusCode` and `body` (parsed JSON or string).

Retries
-------

[](#retries)

The SDK automatically retries failed requests with exponential backoff:

- **429 (rate limited)** -- Retries after the duration specified in the `Retry-After` header
- **5xx (server errors)** -- Retries with exponential backoff (0.5s, 1s, 2s, ...)
- **Connection errors and timeouts** -- Retried with the same backoff schedule

By default, the SDK retries up to 3 times. Set `maxRetries: 0` to disable:

```
$client = new Administrate(apiKey: 'sk_live_...', maxRetries: 0);
```

Requirements
------------

[](#requirements)

- PHP 8.1+
- [Guzzle](https://docs.guzzlephp.org/) >= 7.5

License
-------

[](#license)

MIT

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance83

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

89d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0ecc50713bd43488411731eca85939fd98612dfdbb5d1bd2edde9d3b7acca9ab?d=identicon)[mpclarkson](/maintainers/mpclarkson)

---

Top Contributors

[![mpclarkson](https://avatars.githubusercontent.com/u/4843821?v=4)](https://github.com/mpclarkson "mpclarkson (1 commits)")

---

Tags

apisdkautomationn8nadministrate

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/administrate-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/administrate-sdk/health.svg)](https://phpackages.com/packages/administrate-sdk)
```

###  Alternatives

[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[square/square

Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.

793.4M21](/packages/square-square)[mailchimp/transactional

458.9M16](/packages/mailchimp-transactional)[resend/resend-php

Resend PHP library.

574.7M21](/packages/resend-resend-php)[mozex/anthropic-php

Anthropic PHP is a supercharged community-maintained PHP API client that allows you to interact with Anthropic API.

46365.1k13](/packages/mozex-anthropic-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)