Skip to content

API Quickstart

Make your first API call in under 5 minutes.

1. Get an Access Token

The API uses OAuth 2.0 bearer tokens (Laravel Passport). Obtain an access token from Vellocity's OAuth token endpoint (/oauth/token), or apply for OAuth client credentials through the Embedded Partner Program. Keep the token server-side and send it on every request. See Authentication for the full flow and scopes.

“Settings → API Keys” is not a Vellocity token

That dashboard screen stores your own AI-provider credentials (OpenAI/Anthropic/Gemini/Bedrock) — it does not issue a Vellocity API token.

2. Make Your First Request

All API requests use the base URL https://api.vell.ai/api/v1 and require your access token in the Authorization header. A quick way to confirm your token works is to fetch your own account:

curl -s https://api.vell.ai/api/v1/user \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json" | python3 -m json.tool

import requests

resp = requests.get(
    "https://api.vell.ai/api/v1/user",
    headers={"Authorization": "Bearer ACCESS_TOKEN"},
)
print(resp.status_code, resp.json())

const resp = await fetch("https://api.vell.ai/api/v1/user", {
  headers: { Authorization: "Bearer ACCESS_TOKEN" },
});
console.log(resp.status, await resp.json());

A 200 returns the authenticated account's profile and confirms your token is valid. A 401 means the token is missing or invalid — see Authentication.

3. Try a Content Generation Call

AI Writer uses a two-step flow: first create the output record with POST /aiwriter/generate (which returns a message_id), then stream the result with POST /aiwriter/generate-output. See the AI Writer API for every template and its required fields.

import requests

API = "https://api.vell.ai/api/v1"
HEADERS = {"Authorization": "Bearer ACCESS_TOKEN", "Content-Type": "application/json"}

# Step 1 — create the output record
resp = requests.post(f"{API}/aiwriter/generate", headers=HEADERS, json={
    "post_type": "blog_intros",
    "title": "Cloud Cost Optimization",
    "description": "How to reduce AWS spend by 40%",
    "creativity": 0.7,
    "maximum_length": 300,
    "number_of_results": 1,
})
msg = resp.json()  # -> {"message_id": 456, ...}

# Step 2 — stream the generated text with the message_id from Step 1
stream = requests.post(f"{API}/aiwriter/generate-output", headers=HEADERS, json={
    "message_id": msg["message_id"],
    "creativity": 0.7,
    "maximum_length": 300,
    "number_of_results": 1,
}, stream=True)

for line in stream.iter_lines():
    text = line.decode()
    if text.startswith("data: ") and text != "data: [DONE]":
        print(text[6:], end="")

# Step 1 — create the output record; note the message_id in the response
curl -X POST https://api.vell.ai/api/v1/aiwriter/generate \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"post_type":"blog_intros","title":"Cloud Cost Optimization","description":"How to reduce AWS spend by 40%","creativity":0.7,"maximum_length":300,"number_of_results":1}'

# Step 2 — stream the result using the message_id returned by Step 1
curl -N -X POST https://api.vell.ai/api/v1/aiwriter/generate-output \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message_id":456,"creativity":0.7,"maximum_length":300,"number_of_results":1}'

Streaming responses

generate-output returns Server-Sent Events (SSE); each line is prefixed data: and the stream ends with data: [DONE]. See the AI Writer API for full details.

4. Understand the Response Format

All endpoints return a consistent JSON envelope:

{
  "success": true,
  "data": { },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

Errors follow the same structure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The message_id field is required"
  }
}

See Errors & Rate Limits for the full error code reference.

What's Next?

AI Content

Generate blog posts, social copy, and marketing content.

AI Writer API | AI Chat API

AI Images

Generate images with DALL-E, Stable Diffusion, and Flux.

AI Image API

GTM Automation

Schedule events, manage workflows, and automate campaigns.

Content Workflow API | GTM Schedule API

Partner Integration

Manage listings, co-sell deals, and analytics programmatically.

Partner API | Webhooks