VINwriter — API Documentation

1. Authentication

All requests require an X-API-Key header. Generate your key in the VINwriter app under Admin → API Access (Unlimited plan only). Keep it secret — treat it like a password.

curl https://vinwriter.ai/app/api/v1/status \
  -H "X-API-Key: vw_live_YOUR_KEY_HERE"

$ch = curl_init("https://vinwriter.ai/app/api/v1/status");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: vw_live_YOUR_KEY_HERE"],
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

const response = await fetch("https://vinwriter.ai/app/api/v1/status", {
  headers: { "X-API-Key": "vw_live_YOUR_KEY_HERE" }
});
console.log(await response.json());

import requests

r = requests.get(
    "https://vinwriter.ai/app/api/v1/status",
    headers={"X-API-Key": "vw_live_YOUR_KEY_HERE"},
)
print(r.json())

2. Rate Limits

1,000 requests per day, resetting at 00:00 UTC. Exceeding the limit returns 429 Too Many Requests. Monitor usage with GET /v1/status.

POST/v1/generate

Generate a vehicle listing.

Field	Required	Description
`year`	yes	Model year, e.g. `2023`
`make`	yes	Manufacturer, e.g. `BMW`
`model`	yes	Model, e.g. `330i`
`trim`	no	Trim / variant
`colour`	no	Exterior colour
`mileage`	no	Mileage in km
`price`	no	Asking price in dollars
`options`	no	Comma-separated package / feature list
`tires`	no	Array: `["Summer","Winter"]`
`tone`	no	`REFINED` (default) · `CHARGED` · `RUGGED` · `APPROACHABLE`
`length`	no	`Snapshot` · `Showcase` (default) · `Full Feature`
`language`	no	`en` (default) · `fr` · `es` · `ar` · `pt`

curl https://vinwriter.ai/app/api/v1/generate \
  -H "X-API-Key: vw_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "year": "2023",
    "make": "BMW",
    "model": "330i",
    "trim": "xDrive",
    "mileage": "12000",
    "price": "52999",
    "tone": "REFINED",
    "length": "Showcase",
    "language": "en"
  }'

$body = json_encode([
    "year" => "2023", "make" => "BMW", "model" => "330i",
    "trim" => "xDrive", "mileage" => "12000",
    "tone" => "REFINED", "language" => "en",
]);

$ch = curl_init("https://vinwriter.ai/app/api/v1/generate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: vw_live_YOUR_KEY_HERE",
        "Content-Type: application/json",
    ],
]);
$res = json_decode(curl_exec($ch), true);
echo $res["description"];

const res = await fetch("https://vinwriter.ai/app/api/v1/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "vw_live_YOUR_KEY_HERE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    year: "2023", make: "BMW", model: "330i",
    trim: "xDrive", tone: "REFINED"
  })
});
const data = await res.json();
console.log(data.description);

import requests

r = requests.post(
    "https://vinwriter.ai/app/api/v1/generate",
    headers={
        "X-API-Key": "vw_live_YOUR_KEY_HERE",
        "Content-Type": "application/json",
    },
    json={
        "year": "2023", "make": "BMW", "model": "330i",
        "trim": "xDrive", "tone": "REFINED",
    },
)
print(r.json())

Returns description, features (array), generation_id, credits_remaining.

GET/v1/generations

List your generations (paginated). Filter with query params.

Param	Description
`page`	1-based page number (default 1)
`limit`	Results per page (default 20, max 100)
`make` / `model`	Filter by exact match
`language`	Filter by generation language
`date_from` / `date_to`	YYYY-MM-DD range

curl "https://vinwriter.ai/app/api/v1/generations?page=1&limit=20&make=BMW" \
  -H "X-API-Key: vw_live_YOUR_KEY_HERE"

$ch = curl_init("https://vinwriter.ai/app/api/v1/generations?page=1&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: vw_live_YOUR_KEY_HERE"],
]);
$res = json_decode(curl_exec($ch), true);
foreach ($res["generations"] as $g) echo $g["id"], " ", $g["make"], "\n";

const res = await fetch(
  "https://vinwriter.ai/app/api/v1/generations?page=1&limit=20",
  { headers: { "X-API-Key": "vw_live_YOUR_KEY_HERE" } }
);
const { generations, total } = await res.json();
console.log(`${total} total`);

import requests

r = requests.get(
    "https://vinwriter.ai/app/api/v1/generations",
    params={"page": 1, "limit": 20},
    headers={"X-API-Key": "vw_live_YOUR_KEY_HERE"},
)
for g in r.json()["generations"]: print(g["id"])

GET/v1/generations/{id}

Retrieve a single generation's full content including description + features.

curl https://vinwriter.ai/app/api/v1/generations/42 \
  -H "X-API-Key: vw_live_YOUR_KEY_HERE"

$ch = curl_init("https://vinwriter.ai/app/api/v1/generations/42");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: vw_live_YOUR_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);

const res = await fetch(
  "https://vinwriter.ai/app/api/v1/generations/42",
  { headers: { "X-API-Key": "vw_live_YOUR_KEY_HERE" } }
);
console.log((await res.json()).generation);

r = requests.get(
    "https://vinwriter.ai/app/api/v1/generations/42",
    headers={"X-API-Key": "vw_live_YOUR_KEY_HERE"},
)

GET/v1/status

Account snapshot: plan, status, generations used/remaining, image credits, API usage today.

curl https://vinwriter.ai/app/api/v1/status \
  -H "X-API-Key: vw_live_YOUR_KEY_HERE"