@pouchy_ai/admin-sdk

Typed TypeScript client for the Pouchy Admin API — everything the dashboard does, headless. Manage agents, secret keys, end users, knowledge, skills, channels, schedules, webhooks and credentials; read usage, billing, traces and audit logs. Zero runtime dependencies (uses the global fetch).

The Admin API is authenticated with a project-scoped Admin key (pchy_admin_…, from the dashboard Admin Keys page). The project is implied by the key — you never pass a project id.

Install

npm i @pouchy_ai/admin-sdk

Quickstart

import { createAdminClient } from '@pouchy_ai/admin-sdk';

const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });

// List agents
const { agents } = await admin.listAgents();

// Create + publish an agent
const { agent } = await admin.createAgent({
  name: 'Support Bot',
  archetype: 'support',
  systemPrompt: 'You are a concise, friendly support agent.'
});
await admin.updateAgent(agent.agentId, { status: 'published' });

// Mint a secret key for your backend to open end-user sessions with
const { key } = await admin.createKey({ label: 'prod-backend', env: 'live' });
console.log(key); // the plaintext token — shown ONCE

// Read this month's usage
const { usage } = await admin.getUsage();
console.log(usage.mau, '/', usage.mauLimit, 'MAU');

// Equip an agent with ANY skill — including a docs-only skill.md that has no
// `tools:` block — entirely via the API:
const { skill } = await admin.installSkill({
  md: '---\nname: echo-probe\nallowed_domains:\n  - postman-echo.com\n---\nGET https://postman-echo.com/get echoes the request.'
});
await admin.updateAgent(agent.agentId, { skills: [skill.slug] }); // attach to the agent
const armed = await admin.grantSkill(skill.slug, {
  freeHttp: true,
  grantedDomains: ['postman-echo.com'] // unioned with the manifest's allowed_domains
});
console.log(`armed — ${armed.reprovisioned} running instance(s) updated`);
// The agent can now drive the API from the skill's prose via http_request.

Options

createAdminClient({
  adminKey: 'pchy_admin_…',   // required
  baseUrl: 'https://pouchy.ai/v1/admin', // optional (self-host / staging)
  fetch: myFetch,             // optional (Node <18, or tests)
  timeoutMs: 30_000           // optional per-request timeout (default 30s)
});

Errors

Every method throws AdminApiError on failure — a non-2xx response, a network error, or a timeout. Transport failures (network/DNS/timeout) carry status: 0; HTTP errors carry the real status and the server's error string:

import { AdminApiError } from '@pouchy_ai/admin-sdk';
try {
  await admin.getAgent('nope');
} catch (e) {
  if (e instanceof AdminApiError) console.error(e.status, e.message); // 404 "unknown agent"
}

Surface

| Area | Methods | | --- | --- | | Agents | listAgents · createAgent · getAgent · updateAgent · deleteAgent | | Voices | listVoices({ gender?, age?, locale? }) — catalog for programmatic voice selection (each CatalogVoice carries age) | | Secret keys | listKeys · createKey · revokeKey · rotateKey (24 h grace) | | End users | listUsers({ limit?, cursor? }) (cursor-paginated — the response's nextCursor feeds the next page; filter variants: external_user_id / external_user_prefix) · setUserSuspended · deleteUser · getUserWallet · getUserTraces · importUsers · exportUser · getUserSessions · getUserTurns | | Knowledge | listKnowledge · ingestKnowledge · deleteKnowledge | | Skills | listSkills · installSkill · updateSkill · setSkillRate · setSkillDailyCap · grantSkill (free-HTTP) · compileSkill (prose→tools) · uninstallSkill | | Credentials | listCredentials · putCredentials · deleteCredentials | | Channels | listChannels · createChannel · getChannel · updateChannel · deleteChannel | | Schedules | listSchedules · createSchedule · getSchedule · updateSchedule · deleteSchedule | | Webhooks | listWebhooks · createWebhook · updateWebhook · rotateWebhookSecret · deleteWebhook · testWebhook · redeliverWebhook | | Reporting | getUsage · getBilling · getTracesSummary · getRecentTraces · getLogs · getProject · updateProject | | Escape hatch | request(method, path, body?) — any endpoint not yet typed |

OpenAPI

The machine-readable contract is served at GET https://pouchy.ai/v1/admin/openapi (OpenAPI 3.1, public). Import it into Postman / Swagger UI, or generate a client in any other language with openapi-generator.

License

SEE LICENSE IN LICENSE.