Introduction

Base URL

The base URL for all requests to the Inconvo API is:

https://app.inconvo.ai/api/v1

Authentication

The Inconvo API uses API keys for authentication. Create, manage, and learn more about API keys in your organization settings.

Remember that your API key is a secret! Do not share it with others or expose it in any client-side code (browsers, apps). API keys should be securely loaded from an environment variable or key management service on the server.

API keys should be provided via HTTP Bearer authentication.

Authorization: Bearer INCONVO_API_KEY

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code	Description
200	Request succeeded
400	Bad request — invalid parameters or missing required fields
401	Unauthorized — invalid or missing API key
403	Forbidden — valid key but insufficient permissions
404	Not found — resource does not exist
429	Rate limited — too many requests
500	Internal server error

Error responses return a JSON body:

{
  "error": {
    "message": "Invalid userContext",
    "type": "bad_request",
    "code": 400
  }
}

Response Format

All conversation responses return an InconvoResponse object with a type field indicating the format:

• text — A plain-text answer
• chart — A Vega-Lite chart specification
• table — Structured tabular data with head and body arrays

When stream: true is set, the API returns Server-Sent Events instead. See the Streaming guide for details.

SDKs

Official SDKs are available for integrating with the Inconvo API:

# Node.js SDK
npm install @inconvoai/node

# Vercel AI SDK integration
npm install @inconvoai/vercel-ai-sdk

# AI SDK tools (for assistant-ui and other AI SDK frameworks)
npm install @inconvoai/node-ai-sdk

MCP Servers API

The MCP servers API lets you register and delete tenants from an agent’s MCP server.

Conversations API

The Conversations API lets you send messages to an analytics agent and receive structured responses as text, charts, or tables. You can also log feedback on each response to track quality and guide improvements.