Getting started

Introduction

The Zeevaa API lets your own code talk to an assistant you built in Studio — with your interface, in your product.

An assistant you build in Studio already has two ways to reach people: a shareable link, and an embeddable widget for your own site. Both come with our interface.

The API is the third way, and it comes with none. You get an endpoint and a key. Everything a visitor sees is yours to design.

What you can build#

The same assistant — its instructions, its knowledge, its catalogue, its voice, its webhooks — behind whatever surface you want:

  • A chat panel that matches your product instead of approximating it
  • A search page that queries your catalogue and renders your own cards
  • A voice interface inside a mobile app
  • A support flow that opens a conversation, reads the transcript, and files a ticket from it
  • An internal tool that never faces the public at all

What stays on our side#

You are not rebuilding the assistant, only its interface. Everything below the surface keeps working exactly as it does on the shared link:

Instructions and personaComposed at boot from what you configured
Knowledge searchSemantic retrieval over your linked bases
Catalogue searchFilters compiled into real SQL, not guessed at
Tools and webhooksYour endpoints, called with your credentials
VoiceSynthesis and transcription on your provider keys
TranscriptsEvery turn stored, readable back, with timings
UsageMetered per key, visible in the dashboard

Change an assistant's instructions in Studio and your integration picks them up on the next turn. There is nothing to redeploy.

How it fits together#

Three ideas, and the whole API follows from them.

An assistant is what you built in Studio. It has an id. That id is what your code addresses.

A session is one conversation. You open it, send turns to it, and end it. It holds the transcript, so your code never has to.

A turn is one message in and one reply out. The reply streams back token by token, along with any tools the assistant used and any records it found.

Terminal
# open a conversation
POST /v1/assistants/{assistant_id}/sessions   → { "session_id": "…" }

# say something
POST /v1/assistants/{assistant_id}/chat       → streamed reply

# close it
POST /v1/sessions/{session_id}/end

That is the entire core of it. Voice, transcripts and usage are additions to this shape, not departures from it.

Server-side only#

Your API key belongs on your server and nowhere else. A key in browser JavaScript is visible to anyone who opens developer tools, and from there it spends your credits.

This is not a limitation you have to work around — it is a proxy route you write once. The Next.js guide has one that covers every endpoint, including streaming, in about thirty lines.

Important

There is no browser-safe key. If a request needs to reach us from a page, it goes through your backend first.

Where to go next#