Providers

​

Ownership & scoping

• Providers are Domain-scoped, never per-user. On a runtime-plane client (externalUserId set), list() returns an empty array and get()/update()/delete()/testConnection()/ getModels() return a 404 PersonaApiError — not because the Provider doesn’t exist, but because that credential can never be its owner (existence-hiding, same as everywhere else).
• list() has no pagination envelope and no page/limit/search params — Providers have no discovery concept, so it returns a plain Provider[].

​

Methods

​

create(input, idempotencyKey?)

const provider = await persona.providers.create({
  label: 'OpenAI (prod)',
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!, // encrypted at rest; never returned in any response
  defaultModel: 'gpt-4o-mini',
  isDefault: true, // optional, defaults to false
});

• apiKey is write-only — it never appears on the returned Provider or any later response.
• isDefault (optional, default false): at most one Provider per Domain may be the default. The default Provider is used as the fallback when an Agent has no providerId.
• The optional trailing idempotencyKey is sent as the Idempotency-Key header — see Idempotency.

​

list()

const all: Provider[] = await persona.providers.list();

​

get(providerId)

​

update(providerId, input)

await persona.providers.update(provider.id, {
  defaultModel: 'gpt-4o',
  isDefault: true,
});

• apiKey is optional here: omitting it leaves the existing key untouched; passing a new one replaces the stored key entirely.

​

delete(providerId)

​

testConnection(providerId)

const { success, message } = await persona.providers.testConnection(provider.id);

• Returns { success: boolean, message: string }.
• success: false means the call reached the endpoint but it rejected the credentials/URL — that’s a result, not a thrown error. A genuinely unreachable endpoint (DNS failure, etc.) throws instead.

​

getModels(providerId)

​

getUsage(providerId)

const { agentCount, agents } = await persona.providers.getUsage(provider.id);

​

bulkDelete(ids)

const { deleted, failed } = await persona.providers.bulkDelete([provider.id]);

• Up to 100 ids per call — a request over that limit is rejected with a 400 before anything is deleted.
• Returns { deleted: string[], failed: { id, reason }[] }.

​

Complete example

import { PersonaClient } from '@personaai/sdk';

const persona = new PersonaClient({
  baseUrl: process.env.PERSONA_BASE_URL!,
  credential: process.env.PERSONA_CREDENTIAL!,
});

const provider = await persona.providers.create({
  label: 'OpenAI (prod)',
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  defaultModel: 'gpt-4o-mini',
});

console.log(await persona.providers.testConnection(provider.id));
console.log(await persona.providers.getModels(provider.id));

const { agentCount } = await persona.providers.getUsage(provider.id);
if (agentCount === 0) {
  await persona.providers.delete(provider.id);
}