# @gpt-platform/admin > **🚧 GPT Integrators — Internal Use Only.** This SDK is published for use by GPT Integrators during platform testing and buildout. It is **not** offered for general public access at this time and is **not ready for public release**. Do not redistribute, share credentials, or build production integrations against this package outside of authorized GPT Integrator engagements. The official TypeScript Admin SDK for the GPT Platform — ISV administration across tenants, workspaces, applications, billing, webhooks, and 60+ domain namespaces covering CRM, scheduling, clinical, forms, invoices, campaigns, direct email, voice, agent executions, Reactor pipelines, contracts, meetings, cases, human-review queues, multi-channel messaging, managed OAuth connectors, compliance (HIPAA/GDPR/PCI), brand identities + themes, and more. [![npm version](https://img.shields.io/npm/v/@gpt-platform/admin.svg)](https://www.npmjs.com/package/@gpt-platform/admin) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ⚠️ **Server-side only.** This SDK requires admin privileges. Never expose admin tokens in browser code. --- ## For AI Coding Assistants > **TL;DR:** > > ```typescript > import { GptAdmin } from "@gpt-platform/admin"; > const admin = new GptAdmin({ > baseUrl: "https://api.gpt-core.com", > token: process.env.ADMIN_JWT_TOKEN, > applicationId: process.env.APPLICATION_ID, > }); > ``` > > See [llms.txt](llms.txt) for the complete AI-readable SDK reference. --- ## Features - **60+ domain namespaces** — Full admin surface across tenants, workspaces, applications, CRM, scheduling, clinical, forms, invoices, campaigns, direct email, voice, agent executions, Reactor pipelines, compliance (HIPAA/GDPR/PCI), audit, brand identities + themes, multi-channel messaging, and more - **Fully typed** — Auto-generated types from OpenAPI specs - **Runtime validation** — Zod schemas for request validation - **Stripe-style API versioning** — `Accept: application/vnd.api+json; version=YYYY-MM-DD` - **SSE streaming** — Real-time agent execution events with multi-agent delegation tree queries - **Comprehensive error handling** — Detailed context on every error - **JSON:API envelope unwrapping** — Automatic ## Installation ```bash npm install @gpt-platform/admin # or yarn add @gpt-platform/admin # or pnpm add @gpt-platform/admin ``` ## Quick Start ```typescript import { GptAdmin } from "@gpt-platform/admin"; const admin = new GptAdmin({ baseUrl: "https://api.gpt-core.com", token: process.env.ADMIN_JWT_TOKEN!, // Admin JWT or sk_srv_… server key applicationId: process.env.APPLICATION_ID!, }); // List tenants const tenants = await admin.tenants.list(); // Storage stats const stats = await admin.storage.stats(); // Active webhooks const webhooks = await admin.webhooks.configs.list(); ``` ## Configuration ```typescript const admin = new GptAdmin({ baseUrl: "https://api.gpt-core.com", // Required: API base URL token: "admin-jwt-token", // Required: Admin JWT or sk_srv_… applicationId: "your-app-id", // Required: Application ID apiVersion: "2026-05-13", // Optional: Pin API version }); ``` ### Environment Variables ```bash # .env ADMIN_API_URL=https://api.gpt-core.com ADMIN_JWT_TOKEN=your-admin-jwt-token APPLICATION_ID=your-application-id ``` ```typescript // lib/admin-client.ts import { GptAdmin } from "@gpt-platform/admin"; export const admin = new GptAdmin({ baseUrl: process.env.ADMIN_API_URL!, token: process.env.ADMIN_JWT_TOKEN!, applicationId: process.env.APPLICATION_ID!, }); ``` ## API Versioning The SDK uses Stripe-style API versioning. Every request includes the SDK's built-in API version in the `Accept` header automatically. Pin a specific version for production: ```typescript const admin = new GptAdmin({ baseUrl: "https://api.gpt-core.com", token: process.env.ADMIN_JWT_TOKEN!, applicationId: process.env.APPLICATION_ID!, apiVersion: "2026-05-13", }); ``` Discover available versions with `GET /api-versions`. ## API Reference (Highlights) ### Tenancy ```typescript // Tenants const tenants = await admin.tenants.list(); const tenant = await admin.tenants.create({ name: "Acme Inc.", slug: "acme" }); await admin.tenants.update(tenant.id!, { name: "Acme Co." }); // Workspaces (across tenants) const workspaces = await admin.workspaces.list(); const ws = await admin.workspaces.create({ name: "Engineering", slug: "engineering", tenant_id: tenant.id!, }); // Applications (ISV products) const apps = await admin.applications.list(); // Invitations await admin.invitations.create({ email: "user@example.com", role: "admin" }); ``` ### Webhooks ```typescript // Configs const configs = await admin.webhooks.configs.list(); const webhook = await admin.webhooks.configs.create( "Order Notifications", "https://your-server.com/webhook", ["document.analyzed", "thread.message.created"], process.env.APPLICATION_ID!, ); await admin.webhooks.configs.test(webhook.id!); await admin.webhooks.configs.update(webhook.id!, { enabled: false }); // Deliveries const deliveries = await admin.webhooks.deliveries.list(); await admin.webhooks.deliveries.retry("delivery-id"); ``` ### System Messages ```typescript // Platform-wide ToS, privacy policy, welcome, and announcements const messages = await admin.systemMessages.list(); const announcement = await admin.systemMessages.create({ type: "announcement", title: "Scheduled maintenance", content: "We will be down Sunday 02:00–03:00 UTC.", }); await admin.systemMessages.publish(announcement.id!); await admin.systemMessages.unpublish(announcement.id!); ``` ### Storage Administration ```typescript const stats = await admin.storage.stats(); const wsStats = await admin.storage.stats("workspace-id"); const buckets = await admin.storage.buckets.list(); const bucket = await admin.storage.buckets.get("bucket-id"); const objects = await admin.storage.buckets.objects("bucket-id"); ``` ### Accounts + Billing ```typescript const accounts = await admin.accounts.list(); await admin.accounts.credit("account-id", 1000, "Bonus credits"); await admin.accounts.debit("account-id", 500, "Usage charge"); // Plans, capabilities, billing const plans = await admin.billing.plans.list(); const capabilities = await admin.capabilities.list(); ``` ### Documents ```typescript // admin.documents covers report generation helpers (generatePdf, emailReport). // Bulk document operations live on the extraction sub-namespace: await admin.extraction.documents.bulkDelete(["doc-1", "doc-2"]); await admin.extraction.documents.bulkReprocess(["doc-1", "doc-2"]); ``` ### API Keys ```typescript const keys = await admin.apiKeys.list(); await admin.apiKeys.create({ name: "Production server key", scopes: ["read:agents", "write:agents"], }); await admin.apiKeys.rotate("key-id"); await admin.apiKeys.revoke("key-id"); ``` ### Executions (Agent Streaming) ```typescript // Start an agent execution const execution = await admin.executions.start(agentId, { input: { task: "Process this data" }, }); // Stream events in real time const stream = admin.executions.stream(execution.id); for await (const event of stream) { switch (event.type) { case "token_delta": process.stdout.write(event.data.content); break; case "tool_call": console.log(`Tool: ${event.data.name}`); break; case "done": console.log(`Status: ${event.data.status}`); break; } } // Multi-agent delegation tree const tree = await admin.executions.tree(rootExecutionId); const children = await admin.executions.children(parentExecutionId); ``` ## Domain Namespaces The admin SDK exposes 60+ namespaces. The full set, with one-line domain summaries, is in [llms.txt](llms.txt). Selected highlights: | Namespace | Domain | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `admin.tenants` | Tenant CRUD | | `admin.workspaces` | Workspace management within tenants | | `admin.applications` | ISV application configuration | | `admin.invitations` | Tenant + workspace invitations | | `admin.users` | User administration | | `admin.userProfiles` | User profile management | | `admin.roles` | Role definitions | | `admin.permissions` | Permission registry | | `admin.scopes` | API key scope catalog | | `admin.accessGrants` | Access grant administration | | `admin.ownershipTransfers` | Tenant ownership transfer flows | | `admin.accounts` | Account credit/debit, balance management | | `admin.billing` | Plans, capabilities, usage events, wallet mutations | | `admin.capabilities` | Capability registry per plan | | `admin.apiKeys` | API key allocation, rotation, revocation | | `admin.audit` | Audit log queries | | `admin.webhooks` | Webhook configs + deliveries | | `admin.systemMessages` | Platform-wide ToS, privacy policy, welcome, announcements | | `admin.storage` | Bucket + object administration | | `admin.crm` | Contacts, companies, deals, pipelines (admin) | | `admin.crmClusters` | CRM relationship discovery | | `admin.scheduling` | Events, availability, calendars (admin) | | `admin.clinical` | Patients, sessions, notes (admin) | | `admin.forms` | Form definitions, publications, submissions (admin) | | `admin.invoices` | Invoice rules, payments, recurring generation (admin) | | `admin.campaigns` | Campaign + recipient management (admin) | | `admin.email` | Direct email, sender profiles, tracking (admin) | | `admin.support` | Tickets, queues, SLA (admin) | | `admin.cases` | Case management (admin) | | `admin.contracts` | AI contract lifecycle, clauses, renewal alerts (admin) | | `admin.meetings` | AI meeting transcription, summary, action items (admin) | | `admin.reviews` | Review queues (admin) | | `admin.recipes` | Recipes, shopping lists, nutrition (admin) | | `admin.documents` | Document administration + bulk ops | | `admin.extraction` | Extraction pipeline administration | | `admin.executions` | Agent execution management + multi-agent delegation trees | | `admin.pipelines` | Pipeline definitions | | `admin.pipelineExecutions` | Pipeline run management | | `admin.pipelineNodes` | Pipeline node definitions | | `admin.pipelineNodeExecutions` | Pipeline node execution telemetry | | `admin.agents` | Agent CRUD, versioning, training (admin) | | `admin.ai` | LLM operations (admin) | | `admin.models` | Model catalog | | `admin.threads` | Thread administration | | `admin.compliance` | Full compliance admin surface — breach incidents, BAAs, GDPR DSRs, retention policies, audit chain, access logs, amendments, disclosures, ePHI assets, risk assessments, policy reviews, CDE scope, requirements, document templates, and compliance posture | | `admin.connectors` | Managed OAuth + adapters | | `admin.crawler` | Web crawling administration | | `admin.imports` | Bulk import administration | | `admin.voice` | Voice sessions, STT/TTS administration | | `admin.preferences` | User preferences administration | | `admin.themes` | Design tokens + theme versions | | `admin.brandIdentities` | Tenant/application brand identity | | `admin.platformTones` | Platform tone configuration | | `admin.claimedDomains` | Domain ownership | | `admin.portal` | ISV end-user portal | | `admin.social` | Social account administration | | `admin.channels` | Scoped channel-token exchange (admin) | | `admin.content` | Generic content operations | | `admin.registry` | Service/feature registry | | `admin.projects` | Project administration | ## Bulk Operations All bulk operations support 1–100 items per request with Zod-validated payloads. ```typescript const docIds = ["doc-1", "doc-2", "doc-3"]; await admin.extraction.documents.bulkDelete(docIds); await admin.extraction.documents.bulkReprocess(docIds); ``` ## Security ⚠️ **Admin SDK is server-side only.** - Never use admin tokens in browser code - Store credentials in environment variables or secret managers - Rotate admin tokens regularly - Audit admin actions - Limit admin access to essential operations ## Error Handling ```typescript try { await admin.accounts.credit("account-id", 1000); } catch (error) { // The SDK throws typed errors with detailed context. // Inspect error.message, error.requestId, error.status. console.error("Admin API error:", error); } ``` ## TypeScript Support Full TypeScript definitions, plus per-namespace subpath imports for faster type resolution: ```typescript import { GptAdmin } from "@gpt-platform/admin"; import type { CrmAPI } from "@gpt-platform/admin/crm"; import type { SchedulingAPI } from "@gpt-platform/admin/scheduling"; ``` ## Testing ```bash bun run test # Unit tests (MSW-mocked) bun run test:coverage # With coverage ``` ## License MIT © GPT Integrators