1. 1
   Create an account

   Sign up and open the API Keys section in your dashboard.

2. 2
   Create your key

   Create a live API key and save it securely when it is shown.

3. 3
   Send your first request

   Send POST /generate to the base URL below with a platform, goal, and topic.

No SDK required

Your first request

curl https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1/generate \
  -H "Authorization: Bearer $MARQAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "topic": "shipping our new content API",
    "goal": "Build awareness",
    "variants": 3
  }'

Header format

curl https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1/generate \
  -H "Authorization: Bearer $MARQAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"twitter","goal":"Build awareness","topic":"launch day"}'

Unauthorized response

{
  "error": "Authentication required."
}

Regenerating a key

From the dashboard, open the API Keys section and click Regenerate key. After confirming, the previous key is revoked immediately and the new secret is shown once. Copy it and update your server-side environment variables right away.

Storing keys

# Set MARQAL_KEY in your server environment to the key from your dashboard.

# usage
curl https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1/generate \
  -H "Authorization: Bearer $MARQAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"linkedin","goal":"Build awareness","topic":"launch day"}'

Body parameters

Append /generate to the base URL above. Send a JSON object with a maximum encoded body size of 16 KiB (16,384 bytes), including all evidence entries. TikTok output is a text script; all platforms return text.

Request

curl https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1/generate \
  -H "Authorization: Bearer $MARQAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "goal": "thought leadership",
    "topic": "shipping AI features",
    "variants": 1,
    "evidence": [
      "The release includes automated ticket triage.",
      "The feature is available to Pro customers."
    ]
  }'

Example response (one variation)

{
  "variations": [
    {
      "id": "v1",
      "tone": "strategic insight",
      "content": "Your generated post appears here."
    }
  ],
  "credits_used": 1
}

A successful response contains a variations array with string id, tone and content fields, plus numeric credits_used. The text above is illustrative; tone labels and content can vary. credits_used is usage metadata, not a payment charge during the free beta.

These limits count admitted requests, not output variations. A request can ask for 1–5 variations. Requests that fail after admission still count toward the minute and daily limits.

Handling 429s

When you exceed the limit, Marqal returns 429 rate_limited with a Retry-After header in seconds. Back off and retry.

# If the response contains Retry-After: 12,
# wait at least 12 seconds before repeating the same POST request.
sleep 12

Error shape

{
  "error": "Missing or invalid field: topic"
}

Rate-limit example (HTTP 429)

{
  "error": "Generation request not admitted.",
  "code": "rate_limited",
  "retry_after_seconds": 12
}

The retry delay varies by request. A 503 limiter_unavailable response also includes Retry-After and retry_after_seconds. Some 502 generation errors include a failed_variations array; do not assume every error has a code.

Handling errors

Check the HTTP status and the error message. When a code field is present, use it for programmatic handling. For rate limits, respect the Retry-After header before retrying.