API reference

Programmatic access to everything the dashboard shows, under /api/tenant/*.

Dashboard APIs accept a scoped tenant API key or an OAuth access token. Terri-native MCP clients discover OAuth metadata at /.well-known/oauth-protected-resource and connect to /mcp with terri.read, terri.act, or terri.manage scopes.

MethodPathAuthPurposeKey request fieldsResponse
GET/api/tenant/usageBearer API key (read)Usage dashboard summary for a billing period.tenantId, invoicePeriod? (query)Totals and cost per meter for the period.
GET/api/tenant/usage-exportBearer API key (read)Download raw usage events.tenantId, invoicePeriod?, format? = csv | json (query)Usage events as a CSV or JSON file.
GET/api/tenant/invoicesBearer API key (read)List invoices with per-meter line items.tenantId, invoicePeriod?, planId? (query)Invoices: line items, credits, subtotals, total.
POST/api/tenant/checkout-sessionBearer API key (billing admin)Start a Stripe checkout for a plan.tenantId, planIdStripe Checkout URL to complete subscription.
POST/api/tenant/billing-portal-sessionBearer API key (billing admin)Open the Stripe billing portal.tenantIdStripe billing portal URL.
GET/api/tenant/audit-eventsBearer API key (read)List audit events for the tenant.tenantId (query)Audit events, newest first.
GET/api/tenant/phone-numbersBearer API key (read)List provisioned phone numbers.tenantId (query)Numbers with capabilities and status.
POST/api/tenant/phone-numbersBearer API key (config admin)Register a phone number for the tenant.tenantId, e164, status?The phone number record after setup.
POST/api/tenant/phone-numbers/:id/agent-configBearer API key (config admin)Bind a phone number to an agent identity, or clear it back to the tenant default.tenantId, agentConfigId | nullThe updated phone number record.
GET/api/tenant/contactsBearer API key (read)List tenant contacts and caller-memory flags.tenantId, limit?, cursor? (query)Contacts with nextCursor when another page is available.
POST/api/tenant/contactsBearer API key (config admin)Import or update up to 500 contacts. Existing contacts match by E.164 phone number.tenantId, contacts[] (phoneE164, name, context?, tags?, agentMemoryEnabled?)imported count.
POST/api/tenant/contacts/:phoneE164Bearer API key (config admin)Replace notes on one contact. Empty context clears notes.tenantId, context?The updated contact record.
DELETE/api/tenant/contacts/:phoneE164Bearer API key (config admin)Delete one contact by E.164 phone number.tenantId (query)deleted: true.
POST/api/tenant/contacts/:phoneE164/memoryBearer API key (config admin)Toggle whether a contact can use caller memory when the selected identity permits it.tenantId, agentMemoryEnabledThe updated contact record.
GET/api/tenant/team-usersBearer API key (read)List team members.tenantId (query)Users with email, role, and status.
POST/api/tenant/team-usersBearer API key (config admin)Invite a team member.tenantId, email, role?The invited user (201).
DELETE/api/tenant/team-users/:userIdBearer API key (config admin)Disable a team member.tenantId (query), userId (path)The disabled user record.
GET/api/tenant/api-keysBearer API key (read)List API keys.tenantId (query)Keys with name, prefix, and role — never the secret.
POST/api/tenant/api-keysBearer API key (config admin)Create an API key.tenantId, name, role?The key record plus its token — shown once (201).
DELETE/api/tenant/api-keys/:apiKeyIdBearer API key (config admin)Revoke an API key.tenantId (query), apiKeyId (path)The revoked key record.
GET/api/tenant/callsBearer API key (read)List call logs.tenantId (query)Calls with direction, duration, and status.
GET/api/tenant/agent-configBearer API key (read)Read the tenant default agent identity.tenantId (query)The tenant default agent configuration. Legacy-compatible endpoint.
POST/api/tenant/agent-configBearer API key (config admin)Create or update the tenant default agent identity.tenantId, displayName, systemPrompt, enabledChannels, …The saved tenant default agent configuration. Legacy-compatible endpoint.
GET/api/tenant/agent-configsBearer API key (read)List the tenant default and phone-number identities.tenantId (query)Agent identity configurations.
POST/api/tenant/agent-configsBearer API key (config admin)Create a phone-number identity.tenantId, displayName, systemPrompt, enabledChannels, …The saved non-default agent identity (201).
POST/api/tenant/agent-configs/:idBearer API key (config admin)Update an agent identity, including promotion to tenant default.Mutable agent identity fields; voice null clears the override.The saved agent identity.