Skip to main content

API Access

Connecting to your agent through the API is like giving your own software a direct phone line to it — instead of a person typing into a chat window, your app sends a message in code and gets the agent's reply back in code. This is the way to plug your agent into a custom app, an internal tool, or any system that should talk to it automatically.

In this guide, API means the connection your software uses to talk to Nirvai. You send a request (the message you're sending) and get back a response (the agent's reply). This page is written for developers, so it's a bit more technical than the rest — but every term is explained the first time it appears.

API channel export showing the API keyImage: API channel export showing the API key

Before you start​

  • A completed agent in the Agent Control Panel
  • The ability to send an HTTP request — that's the standard way programs talk to web services. You can do this from your own code, or test it first with a tool like Postman (a free app for trying out requests by hand)

Setting up API access​

  1. Open your agent in the Agent Control Panel
  2. Click the Channels node
  3. Select API from the Web section
  4. Click Create API Export
  5. An API key is generated — copy it and store it somewhere safe. An API key is a private password that lets your app prove it's allowed to talk to your agent.

Creating an API export and copying the keyImage: Creating an API export and copying the key

warning

Keep your API key secret. Anyone who has it can send messages to your agent and use up your credits. Don't put it in code that runs in a browser or commit it to a public repository — keep it on your server.

Making requests​

Your app sends each message to the agent's endpoint — the specific web address you call on Nirvai. Include your API key so Nirvai knows the request is really from you, then send the message and read back the agent's reply.

curl -X POST https://api.nirvana-ai.app/v1/agent/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "session_id": "user-123"
  }'

What this request does, line by line:

  • POST https://api.nirvana-ai.app/v1/agent/chat — sends ("POST") your message to the agent's endpoint
  • Authorization: Bearer YOUR_API_KEY — proves it's you. Replace YOUR_API_KEY with the key you copied
  • Content-Type: application/json — tells Nirvai the message is in JSON, a common text format for sending structured data
  • message — the text you're sending to the agent
  • session_id — a label you choose that keeps a back-and-forth conversation together (more on this below)

Key concepts​

ConceptDescription
API keyA private password that proves the request is from your app. Sent in the Authorization header (the part of a request that carries identity and settings)
Session IDA label that groups messages into one conversation. Reuse the same ID for follow-up messages so the agent remembers the context
MessageThe text you're sending to the agent
ResponseThe agent's reply, returned in the body of the response
tip

To keep a conversation going, send the same session_id with each message. A new session_id starts a fresh conversation with no memory of what came before — useful when a different user starts chatting.

Use cases​

  • Custom apps — Build your own chat interface that talks to your Nirvai agent
  • Internal tools — Connect your agent to internal dashboards or admin panels
  • Automation — Trigger agent conversations from other systems, scheduled jobs, or automatic alerts when something happens elsewhere
  • Mobile apps — Add your agent to an iOS or Android app

Managing your export​

  • Regenerate key: If your API key is exposed, create a new export and delete the old one. The old key stops working right away.
  • Remove: Deactivate the API export. Existing keys stop working immediately.

Troubleshooting​

ProblemFix
You get a "401 Unauthorized" errorThe API key is missing or wrong. Check it's correct and sent in the Authorization header as Bearer YOUR_API_KEY
The agent doesn't respondMake sure the agent is created and the API export is still active
The conversation doesn't remember contextUse the same session_id for every message that belongs to the same conversation
You get a "Content-Type" or parsing errorSend the body as JSON and include the Content-Type: application/json header

What's next​

To see the no-code ways to put your agent on the web — a floating chat widget or a public link — see the Channels Overview.