API Documentation

Getting started

Quickstart

Generate your first social post in under a minute. The Marqal API is REST-based, returns JSON, and uses standard HTTP status codes.

1
Create an account
Sign up and open the API Keys section in your dashboard.
2
Create your key
Create a live API key and save it securely when it is shown.
3
Send your first request
Call /v1/generate with a platform, goal, and topic.

Base URL·https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1

No SDK required

Official SDKs coming soon.For now, call the API directly with any HTTP client — examples below use cURL, the native fetch in JavaScript, and the requests library in Python.

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
  }'

Was this page helpful?

Security

Authentication

Marqal uses bearer tokens. Send your API key in the Authorization header on every request. Never expose keys in client-side code.

Server-side only.Treat your API key like a password — never embed it in browsers, mobile apps, or public repos.

Header format

curl https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1/generate \
  -H "Authorization: Bearer mq_live_a8f9k2m7x1" \
  -H "Content-Type: application/json"

Unauthorized response

json

{
  "error": {
    "type": "unauthorized",
    "message": "Missing or invalid API key.",
    "code": 401
  }
}

Was this page helpful?

Credentials

API Keys

Each Marqal account can have one active live key in the format mq_live_<random>. Create and manage it from your dashboard.

Field	Type	Description
Prefix	mq_live_	Live API traffic for your Marqal account.
Length	56 chars	The mq_live_ prefix followed by a 48-character random value.
Scope	Account-wide	One active key per account.
Rotation	Instant	Regenerating immediately invalidates the previous key.

Save it when it is shown.Marqal stores only key metadata and a secure hash. The full secret cannot be viewed again after you close the creation dialog.

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.

Plan the cutover.Only one key can be active at a time. Regeneration invalidates the previous key immediately, so be ready to update your deployment as soon as the new secret is shown.

Storing keys

# .env
MARQAL_KEY=mq_live_a8f9k2m7x1

# usage
curl -H "Authorization: Bearer $MARQAL_KEY" https://wjjdnwgkbydxqegfcvty.supabase.co/functions/v1/generate

Was this page helpful?

Endpoints

Generate

Generate a social post tailored to a platform, goal, and topic.

POST/v1/generate

Body parameters

Field	Type	Description
platform	string · required	linkedin · twitter · threads · instagram · tiktok
goal	string · required	The outcome the content should work toward.
topic	string · required	Subject the post should be about.

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"
  }'

Response

json

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

Was this page helpful?

Reference

Rate limits

Operational limits protect reliability during the public beta.

Field	Type	Description
Concurrent requests	2	Maximum in-flight generation requests.
Per minute	8	Maximum generation requests per minute.
Per day	50	Maximum generation requests per day.

Handling 429s

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

# Retry-After: 12
sleep 12 && curl ...

Was this page helpful?

Reference

Errors

Marqal uses conventional HTTP status codes. Some operational errors also include a machine-readable code.

Field	Type	Description
400	-	The request body or one of its fields is invalid.
401	-	Authentication is missing or invalid.
405	-	The HTTP method is not supported.
413	-	The request body is too large.
429	rate_limited	Operational rate limit reached. Retry later.
500	-	An internal server error occurred.
502	-	Generation failed on the provider or validation path.
503	limiter_unavailable or no code	A required authentication or rate-limit service is temporarily unavailable.

Error shape

json

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

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.

Was this page helpful?