CopyBuilder AI
Get API keyLog in
REST API · v1

API Documentation

Programmatically generate AI-powered marketing copy using the CopyBuilder AI REST API. Available on the Agency plan.

Overview

The CopyBuilder AI API lets you integrate AI content generation into your own applications, automations, and workflows. You can generate Google ad copy, Instagram captions, and LinkedIn posts using a simple JSON request.

Agency plan required. API access is not available on Free, Starter, or Pro plans. Upgrade your plan →

Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

Authorization: Bearer cb_live_YOUR_API_KEY

Generate and manage API keys in Dashboard → Settings → API. Keys are shown only once at creation — store them securely.

Endpoint

MethodURLDescription
POST/api/v1/generateGenerate AI content

Request body

Content-Type: application/json

FieldTypeRequiredDescription
contentTypestringYesOne of: google_ad_copy, instagram_caption, linkedin_post
productDescriptionstringYesWhat you're promoting (product, service, or brand)
targetAudiencestringYesWho the content is written for
tonestringNoprofessional (default) | casual | aggressive

Response

A successful response returns HTTP 200 with:

FieldTypeDescription
outputsarrayArray of generated content objects. Shape varies by contentType.
creditsRemainingnumber | nullRemaining credits in your workspace. null for unlimited plans.

Examples

Google Ad Copy — cURL

curl -X POST https://copybuilder.in/api/v1/generate \
  -H "Authorization: Bearer cb_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "google_ad_copy",
    "productDescription": "Cloud accounting software for Indian SMBs",
    "targetAudience": "Finance managers at 10–200 person companies",
    "tone": "professional"
  }'

Response

{
  "outputs": [
    {
      "headlines": [
        "Simplify Your GST Filing Today",
        "Accounting Made Easy for Indian SMBs",
        "Try Free — No Credit Card Needed"
      ],
      "descriptions": [
        "Automate invoices, GST reports, and payroll. Trusted by 5,000+ Indian businesses.",
        "Cloud-based accounting software designed for Indian compliance. Start free."
      ],
      "ctas": ["Start Free Trial", "Book a Demo", "See Pricing"]
    }
  ],
  "creditsRemaining": 487
}

Instagram Caption — request body

{
  "contentType": "instagram_caption",
  "productDescription": "Handmade silver jewellery for modern Indian women",
  "targetAudience": "Women aged 22–35 who follow fashion influencers",
  "tone": "casual"
}

Response

{
  "outputs": [
    {
      "hooks": ["Shine differently. ✨", "Not your average chain."],
      "captions": [
        "Handcrafted. Timeless. Yours.\n\nEvery piece tells a story — what's yours?"
      ],
      "hashtags": ["#SilverJewellery", "#HandmadeJewellery", "#IndianFashion"]
    }
  ],
  "creditsRemaining": 486
}

Error codes

StatusMeaning
400Bad request — missing or invalid fields
401Unauthorized — missing or invalid API key
403Forbidden — workspace is not on Agency plan
429Rate limit exceeded — wait until midnight UTC
500Server error — try again
502AI generation failed — try again
503Service unavailable — server misconfiguration

Error responses always include an error field with a human-readable message.

{
  "error": "Daily rate limit of 100 requests exceeded. Resets at midnight UTC."
}

Rate limits

  • 100 requests / day per workspace on Agency plan
  • Counter resets at midnight UTC
  • Exceeding the limit returns 429 Too Many Requests
  • Higher limits available on Enterprise plans

Ready to integrate?

Get your API key from the Agency plan dashboard.

Get your API key →

API documentation FAQs

Auth, rate limits, error handling, retries, SDKs, security, and how the API integrates into your stack. Open any question for the full answer.

Which plans include access to the CopyBuilder AI API?

API access is exclusive to the Agency plan (₹999/month, billed in INR ex-GST). The Free, Starter, and Pro plans are dashboard-only — they're built for marketers writing copy in the UI, not for developers integrating generation into their own products. The Agency tier was designed specifically for content shops, SaaS companies, and agencies that need programmatic generation — for example, automated content workflows in Zapier/n8n, in-house tools for client onboarding, or AI features inside customer-facing products.

How do I authenticate API requests?

All API requests must include your API key in the Authorization header as a Bearer token, in the format 'Authorization: Bearer cb_live_YOUR_API_KEY'. Generate and manage API keys in Dashboard → Settings → API. Each key is shown in full only once at creation time — copy it and store it in your secrets manager (AWS Secrets Manager, HashiCorp Vault, or your platform's environment variables). After that the dashboard only shows a masked version (cb_live_****abcd). If you lose a key, revoke it and create a new one.

What is the rate limit for the API?

The default rate limit is 100 successful requests per workspace per UTC day on the Agency plan. Failed requests (4xx or 5xx) don't count against the limit. The counter resets at midnight UTC every day. Exceeding the limit returns HTTP 429 with a JSON body containing the reset time. If you need higher limits — for example for an enterprise SaaS integration generating thousands of pieces per day — contact info@arinesolutions.com for a custom rate limit on Enterprise tier. Burst limits within the daily quota are not enforced.

Which content types does the API support?

The current API supports three content types: 'google_ad_copy', 'instagram_caption', and 'linkedin_post'. These are the highest-demand integration types. Facebook ad copy, X / Twitter posts, and Website Blog generation are available in the dashboard but not yet in the API; they're on the Q3 2026 API roadmap. If your integration needs one of those types urgently, contact us — we can sometimes prioritise based on customer need. The contentType field is required and case-sensitive.

What happens if my API key is exposed or leaked?

Revoke the leaked key immediately from Dashboard → Settings → API. Revocation takes effect within 30 seconds across all our edge nodes. Then create a new key, deploy it to your secrets manager, and update your application. Audit your usage logs (also in the API settings page) for any unauthorised generations between exposure and revocation — if you see suspicious activity, email info@arinesolutions.com and we'll review the credit usage and refund any unauthorised consumption. Never commit API keys to version control; use environment variables or a dedicated secrets manager.

Does the API count credits the same way as the dashboard?

Yes. Each successful API generation deducts 1 credit from the workspace balance, identical to dashboard generations. The API response includes a 'creditsRemaining' field so your application can monitor balance and alert when low. On the Agency plan, the dashboard generation is unlimited under fair-use, but the API has a hard daily rate limit of 100 requests as a separate guardrail. If you need more than 100 API calls per day, request an Enterprise rate limit upgrade.

What error codes does the API return and what do they mean?

Standard HTTP status codes: 200 (success), 400 (bad request — missing or invalid fields in your JSON body), 401 (unauthorised — missing or invalid API key), 403 (forbidden — your workspace is not on Agency plan, or the API is disabled), 429 (rate limit exceeded — wait until midnight UTC), 500 (internal server error — retry with backoff), 502 (AI generation provider failed — retry), 503 (service unavailable — server misconfiguration, contact support). Every error response includes an 'error' field with a human-readable message describing what went wrong.

How do I handle retries and backoff for failed requests?

For transient errors (500, 502, 503), use exponential backoff: wait 1 second after the first failure, 2 seconds after the second, 4 seconds after the third, capped at 60 seconds, and retry up to 5 times before logging the failure. For 429 rate-limit errors, parse the 'reset_at' timestamp from the response and wait until then before retrying — don't retry immediately or you'll just get rate-limited again. For 4xx errors (400, 401, 403), don't retry; the request is fundamentally invalid and will fail again. Use a library like axios-retry or got's retry plugin to automate this.

Are API responses streamed or returned all at once?

API responses are returned as a single JSON object after the full generation completes. Streaming responses (Server-Sent Events or chunked transfer) are on the roadmap for Q4 2026 — they'll be useful for building chat-style integrations. For now, expect each request to take 8 to 15 seconds end-to-end depending on the content type and brief complexity. Use a webhook-driven workflow if you need to handle generation asynchronously (call the API from a background worker, store the result, notify your app).

Can I use the API to power a customer-facing AI feature in my SaaS?

Yes — that's a major intended use case. Many of our Agency customers use the API to embed generation inside their own product (for example, an HR SaaS that generates job ad copy from a job description, or a CRM that auto-drafts outreach emails). You're allowed to white-label the output as your own product feature; you just can't expose the API key to end-users (route requests through your backend) and you must comply with our acceptable-use policy. Contact us if you expect to drive 1000+ generations per day — we'll set up a custom Enterprise plan.

Where can I see my API usage and remaining quota?

Dashboard → Settings → API shows real-time usage statistics: today's request count versus the daily limit, this month's total requests, this month's credits consumed, and a per-key breakdown showing which key generated which requests. The 'creditsRemaining' field in every API response is the authoritative source for your workspace balance. For team coordination, set a Slack/Discord webhook in your code to alert when credits drop below a threshold (for example, 100 credits remaining).

Does the API support batch requests or only single generations?

Currently the API processes one generation per request — there's no batch endpoint. To generate multiple pieces, send multiple parallel requests respecting the 100/day rate limit. Most users find single-request generation simpler to handle anyway, since each generation can be retried independently if it fails. A batch endpoint is on the roadmap for Q4 2026 specifically for enterprise users running large-scale data-augmentation jobs (typically 1000+ generations per batch).

What's the difference between cb_live_ and cb_test_ keys?

Currently we only issue 'cb_live_' production keys. A separate 'cb_test_' sandbox key with mock responses (no credit consumption, fixed test outputs for predictable testing) is on the roadmap. For now, use a separate workspace with a small credit allocation as your dev/staging environment if you need isolated testing — most Agency customers maintain two workspaces (one for production, one for staging) using a single billing account. The two-workspace approach mimics what test keys will eventually provide.

Is there an official SDK or do I have to call the REST API directly?

Currently the REST API is the canonical interface — there's no official SDK for Node.js, Python, or Go yet. The API is simple enough (one POST endpoint, JSON in/out, Bearer auth) that most teams build a thin wrapper in their language of choice in under 30 minutes. Community-maintained SDKs are available on GitHub for Node.js (search 'copybuilder-node') and Python (search 'copybuilder-python'); we link to them in our documentation. Official first-party SDKs are planned for Q1 2027.

How do I get help if my API integration breaks?

Agency-tier customers get priority email support at info@arinesolutions.com with a target response time of 4 business hours. For urgent production issues (your customer-facing feature is down), include the word 'API DOWN' in the subject line and we treat it as a P1 ticket with a 30-minute first-response SLA during business hours (9am-7pm IST, Mon-Fri). Always include the timestamp, request ID (returned in every response header as 'X-Request-Id'), and a sanitised version of the request body so we can reproduce the issue.

Does the API support webhooks for asynchronous generation?

Not yet — generation is currently synchronous (you make a request, wait 8 to 15 seconds, receive the response). Webhook-based async generation is on the roadmap for Q4 2026, which will be useful for batch jobs and long-running integrations. For now, the recommended pattern for async work is: make the API call from a background worker (Sidekiq, Celery, AWS Lambda), store the response in your database, and notify your front-end via your own websocket or polling. This decouples your UI from the 8-to-15-second generation latency.