Skip to main content
POST
/
api
/
v1
/
copilot
/
chat
Copilot Chat
curl --request POST \
  --url https://app.nouvel.ai/api/v1/copilot/chat \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messages": [
    {
      "messages[].role": "<string>",
      "messages[].content": "<string>"
    }
  ],
  "productUrl": "<string>",
  "projectId": "<string>"
}
'
{
  "response": "<string>",
  "model": "<string>"
}
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

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

​
Request Body

​
messages
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.
​
productUrl
string
Product URL for competitor ad research. When provided, the copilot fetches competitor ad intelligence from the Foreplay database to inform its responses.
​
projectId
string
UUID of an active project. When provided, the copilot has context about the project’s settings, scenes, scripts, and style configuration.

​
Response

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

​
Example Requests

curl -X POST https://app.nouvel.ai/api/v1/copilot/chat \
  -H "Authorization: Bearer nvl_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Write me 3 Instagram captions for a protein powder targeting gym-goers" }
    ]
  }'

​
Response Examples

{
  "response": "Here are 3 Instagram captions for your protein powder:\n\n1. **The Gains Caption**: \"Every scoop brings you closer to your goals. 25g of pure whey protein, zero compromises. 💪 #FitnessJourney #ProteinPowder\"\n\n2. **The Lifestyle Caption**: \"Morning routine upgrade: coffee ☕ + [Brand] protein shake = unstoppable. What's in your post-workout shake?\"\n\n3. **The Social Proof Caption**: \"10,000+ athletes trust [Brand] for their recovery. Join the movement. Link in bio. 🏋️\"",
  "model": "balanced"
}

​
Error Codes

CodeDescription
400Missing messages array or invalid format
401Invalid or missing API key
402Plan doesn’t include API access
403API key missing copilot:chat permission
429Daily message limit reached. Check resetAt for when the limit resets (midnight UTC)
500Internal server error

​
Context Injection

The copilot automatically enriches its responses with context from your account:
Context SourceWhen Included
Brand kitAlways — business name, description, tone of voice, target audience, color palette, visual style, guardrails
Available avatarsAlways — platform actors + custom avatars you’ve uploaded
Scraped URLsWhen the last user message contains product URLs — they’re scraped, classified, and only product pages are included
Competitor adsWhen productUrl is provided — fetches competitor ad intelligence from the Foreplay ad database
Project contextWhen projectId is provided — includes project style settings, scenes, and scripts

​
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

FeatureDashboardAPI
AuthBrowser session (cookies)API key
Response formatServer-Sent Events (SSE stream)JSON (complete response)
File attachmentsSupportedNot supported
Product contextFull form (actor, language, images)productUrl parameter only
Max durationN/A (streaming)60 seconds
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 data from the Foreplay intelligence database.
Check the X-RateLimit-Remaining header to track your API rate limit, and handle 429 responses gracefully with the resetAt timestamp.