canonical: https://jentic.com/apis/convai.com/convai

# Convai Character API

Jentic publishes the only available OpenAPI specification for Convai Character API, keeping it validated and agent-ready. The Convai Character API lets developers create, update, retrieve, clone, and delete AI characters used in interactive experiences such as games, virtual worlds, and immersive training. The five POST endpoints cover the full character lifecycle, with authentication via the CONVAI-API-KEY header. The Character API requires a Professional Plan or above on Convai.

## For AI agents

Create, update, clone, and delete conversational AI characters on Convai for games and interactive experiences. Agents authenticate with a CONVAI-API-KEY header.

## Scope

Does not run real-time conversation, synthesise voice audio, or render avatars - use for AI character lifecycle management only.

## Capabilities

- Create a new conversational AI character with persona and backstory via `/character/create`
- Update character traits, voice, and knowledge via `/character/update`
- Clone an existing character to spin up variants via `/user/clone_character`
- Retrieve character configuration and metadata via `/character/get`
- Delete a character permanently via `/character/delete`

## Use cases

### Game NPC Authoring

Create and iterate on AI-driven non-player characters for video games and interactive experiences. POST `/character/create` defines the persona, backstory, and voice; `/character/update` tunes responses as designers playtest. Suited to studios building dialogue-rich titles where each NPC needs a distinct personality and the team iterates dozens of times before ship.

Example prompt: Create a Convai character named 'Lyra' with a guarded ranger persona and a calm female voice via `/character/create`

### Virtual Tutor and Trainer Cloning

Build a base AI tutor character once, then clone it via `/user/clone_character` to spin up subject-specific variants such as physics, history, or language tutors. Each clone inherits the base personality and gets domain-specific knowledge layered on with `/character/update.` Useful for ed-tech and corporate training teams maintaining a stable of consistent virtual instructors.

Example prompt: Clone the base 'Tutor' character and update the clone with a chemistry knowledge profile and the name 'Chem Coach'

### Character Lifecycle Management

Maintain a roster of production AI characters by retrieving current state, updating personality drift over time, and removing characters that have been retired from the experience. `/character/get` inspects current config and `/character/delete` removes obsolete entries. Useful for live-service experiences where characters evolve across content updates.

Example prompt: Retrieve the config for character ID abc123, update its voice to a new model, and delete two retired character IDs

### Agent-Driven Character Authoring via Jentic

An AI agent designs and iterates Convai characters through Jentic without holding the API key. The agent searches Jentic for the create or update intent, loads the schema, and executes the POST call with persona inputs. Through Jentic the CONVAI-API-KEY header is injected from the vault so the agent can run authoring loops without secret exposure.

Example prompt: Search Jentic for 'create a Convai character', load the schema, then create a character with a generated persona and report back the character ID

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/character/create` | Create a new AI character |
| POST | `/character/update` | Update an existing character |
| POST | `/character/get` | Retrieve character details |
| POST | `/user/clone_character` | Clone an existing character |
| POST | `/character/delete` | Delete a character |

## Key resources

- **Character** — Create, update, retrieve, and delete AI characters
- **User** — User-scoped operations including character cloning

## Why Jentic

- **Setup:** Wiring the Convai Character API by hand means sending your CONVAI-API-KEY header and coordinating the character create, update, get, clone, and delete calls yourself. Through Jentic you install once, import the Convai Character API from the API Directory, store the api_key once, and your agent calls it.
- **Permission scoping:** The Convai Character API identifies each character in the request body rather than the URL path, so you limit the agent to the operations it needs, such as creating or reading a character, and it can call nothing outside that set. You choose the operations it may call, so destructive ones like deleting a character are not included unless you add them.
- **Credential handling:** Your Convai CONVAI-API-KEY is stored once, encrypted, by your own Jentic One instance and injected into the header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Convai character' or 'clone a character', and Jentic returns the matching Convai operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ElevenLabs API** — Voice synthesis that pairs with Convai characters when custom or cloned voices are needed.
- **OpenAI API** — General-purpose LLM that can power custom NPC dialogue without Convai's character abstractions.
- **Anthropic API** — LLM platform suited to building bespoke dialogue agents with Claude as the reasoning engine.

## FAQ

### Why is there no official OpenAPI spec for Convai Character API?

Convai does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Convai Character API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Convai Character API use?

The API uses an apiKey scheme. Send your key in the CONVAI-API-KEY request header on every call. Through Jentic the key is held in the vault and injected at execution time so it never enters the agent's context window.

### Can I clone an AI character with the Convai Character API?

Yes. POST `/user/clone_character` duplicates an existing character so you can branch a base persona into variants. Use `/character/update` afterwards to layer domain-specific traits, voice, or knowledge onto the clone.

### Do I need a paid plan to use the Convai Character API?

Yes. The Character API requires a Convai Professional Plan or above. The five lifecycle endpoints are gated behind plan-level access - confirm your account tier before integrating.

### What are the rate limits for the Convai Character API?

Rate limits are not declared in the OpenAPI spec. Treat the lifecycle endpoints as soft-limited per CONVAI-API-KEY and back off on HTTP 429 responses. Contact Convai support for documented limits on your plan.

### How do I create a Convai character through Jentic?

Run jentic search for 'create a Convai character', load the returned POST `/character/create` operation, then execute it with your persona, backstory, and voice settings. Jentic injects the CONVAI-API-KEY from the vault and returns the new character ID as a structured result.

### Can I limit what my agent is allowed to do with the Convai Character API?

Yes. Because you run Jentic One yourself and set the rules, you choose exactly which Convai operations your agent may call, such as allowing it to create a character with `/character/create` and read one with `/character/get` while excluding the rest. Since each character is identified in the request body rather than the URL path, the agent can act only on the operations you grant and nothing outside that set. Destructive calls like `/character/delete` stay unavailable unless you deliberately add them, and the CONVAI-API-KEY is injected at execution time so it never reaches the agent.