Skip to main content
POST
Copilot Chat
Send messages to the Nouvel AI copilot for help with ad strategy, caption writing, product research, and creative ideation. This is the API version of the dashboard copilot — it returns a complete JSON response instead of a server-sent event stream.

Authentication

string
required
Your Nouvel API key with copilot:chat permission. Format: Bearer nvl_xxxx

Request Body

array
required
Chat message history. Each message must have role and content.
Include the full conversation history to maintain context. The copilot is stateless — each request is independent.
string
Product URL for competitor ad research. When provided, the copilot fetches competitor ad intelligence to inform its responses.
string
UUID of an active project. When provided, the copilot has context about the project’s settings, scenes, scripts, and style configuration.

Response

string
required
The copilot’s full text response.
string
required
The AI model used (determined by your plan, not configurable via API).

Example Requests

Response Examples

Error Codes

Context Injection

The copilot automatically enriches its responses with context from your account:

Daily Limits

The copilot enforces a daily message limit per user, determined by your plan. The limit resets at midnight UTC. When the limit is reached, the API returns a 429 response with:
  • resetAt — ISO timestamp when the limit resets
  • count — number of messages used today
  • limit — maximum messages allowed per day

Differences from Dashboard Copilot

The API copilot returns the complete response as JSON, making it ideal for automation and integration workflows where you need the full response before proceeding.

Best Practices

The copilot is stateless. To maintain context across turns, include all previous messages in the messages array. This lets the copilot refine and build on previous responses.
When asking about ad strategy or creative angles, include a productUrl to give the copilot access to competitor ad intelligence.
Check the X-RateLimit-Remaining header to track your API rate limit, and handle 429 responses gracefully with the resetAt timestamp.