Getting Started

Glossary

The nouns this API uses, what each one owns, and how they fit together.

OnCore has a small vocabulary, but the pieces compose in ways that are not obvious from any single endpoint. This is the map.

The hierarchy#

text

Organization
└── Tenant                     ← your API key is usually scoped here
    ├── Assistant              ← answers calls and messages
    │   ├── Prompt             (shared, by reference)
    │   ├── Tools              (shared, by reference)
    │   ├── Documents          (shared, attached)
    │   ├── Task groups        (shared, linked)
    │   ├── Capture forms
    │   ├── Transfer reasons
    │   └── SMS reasons
    ├── Phone numbers          ← routed to an assistant
    ├── Calls                  (read-only history)
    └── Conversations          (read-only history)

The pattern worth internalizing: prompts, tools, documents and task groups belong to the tenant, not to an assistant. You define them once and reference them from as many assistants as you like. Deleting an assistant does not delete them.

Core nouns#

Organization — the top of the hierarchy. Owns tenants. An organization key can act on any tenant it owns, but must name which one via X-Tenant-Id.

Tenant — the isolation boundary. Everything below belongs to exactly one tenant, and nothing crosses between them. A RESOURCE_NOT_FOUND on something you can see in the dashboard usually means you are authenticated as the wrong tenant.

Assistant — a configured AI agent that answers calls and, optionally, messages. It is mostly a bundle of references: which voice, which model, which prompt, which tools. See Assistants.

Prompt — a reusable block of instructions. Comes in types — voice, chat, whisper summary — and is attached by id (promptId, chatPromptId). Distinct from developerPrompt, which is written inline on the assistant. See Prompts.

Tool — a function the assistant can call mid-conversation, backed by an HTTP endpoint you control. The description is what the model reads when deciding whether to call it. See Tools.

Document — a plain-text knowledge-base file. Lives in the tenant library and is attached to assistants; attaching does not copy it. See Knowledge base.

Task group — an ordered flow of tasks an assistant works through when taskDrivenMode is on. Linked to assistants, with per-assistant instruction overrides. See Task groups.

Capture form — a structured set of fields the assistant collects during a conversation, so you get typed data rather than a transcript to parse. See Capture forms.

Transfer reason — the conditions under which an assistant hands the call to a human, and where it sends it. Distinct from the transfer mode, which governs how the hand-off is performed. See Transfers.

SMS reason — the conditions under which an assistant texts the caller mid-call, and what it says. See SMS & texting.

Custom instruction — a short titled behavior note attached to an assistant. Up to six. The lightest way to nudge behavior without editing a prompt. See Custom instructions.

Activity#

Call — one voice interaction. Read-only: the API reports on calls, it does not place them. See Calls.

Conversation — the messaging counterpart, covering web chat, SMS and WhatsApp. Also read-only. See Conversations.

End-of-call report — the webhook delivered when a call finishes, carrying transcript, summary, recording and structured data. Almost always better than polling. See End-of-call report.

Configuration#

Voice / Model / Transcriber — the three lookup resources every assistant references by id: how it sounds, how it reasons, how it hears. Read-only catalogs that grow over time. Voice display names are not unique, so always reference by voiceId. See Voices, Models & Transcribers.

Failover number — where a call goes if the assistant cannot handle it. Paired with failoverMode, which when true forwards every call without the assistant answering at all — a deliberate kill switch.

Server URL — where webhooks are delivered. Set per assistant (serverUrl) or per tenant; the assistant-level value wins.

Client server secret — the shared secret used to verify webhooks. Shown on the API Keys page next to your API keys, but it is not an API key and will never authenticate a request.

Terms that trip people up#

Term	Not to be confused with
`developerPrompt`	`promptId` — one is inline text, the other references a shared prompt
Client server secret	API key — one verifies inbound webhooks, the other authorizes outbound requests
Attaching a document	Uploading one — attaching links an existing document to an assistant
`failoverNumber`	Transfer destination — failover is for failure, transfer is for intent
Tenant key	Organization key — the latter needs `X-Tenant-Id` on every request

Introduction — what the platform does.
API conventions — the rules every endpoint follows.
Authentication — key types and scoping.