Introduction

Studio Promote puts the rooftop's own banners and billboards on its vehicles' photos. You create a promotion, choose the vehicles and the images, and Spyne updates the photos. Pause or end it at any time.

Step	Page
1. Get images ready (optional)	List images `GET` · Add an image `POST`
2. Check the request	Check a promotion (dry run) `POST`
3. Go live	Create a promotion `POST`
4. Follow it	List promotions `GET` · Retrieve a promotion `GET`
5. Pause, resume or end	Change status `POST`
6. Clean up	Delete a promotion `DELETE`
Reference	Errors and FAQs

Your first promotion takes three calls: a dry run, the create, then a retrieve to see its status.

Two ways to choose vehicles

Type	Send	Good for
Hand-picked (`custom`)	`vehicles`: up to 500 VINs, stock numbers or registration numbers	A fixed set, such as 10 aged units. A vehicle can be in only one hand-picked promotion at a time.
Filter-based (`dynamic`)	`criteria`: a description, such as every Toyota over $20,000	A changing set. Vehicles that match later get the promotion too.

Before you start

The vehicles must already be in the rooftop's Spyne inventory.
You need an API key for the rooftop from Developer Hub in the Spyne Console. If you don't see Developer Hub, ask your Spyne account manager to turn it on. Keep the key secret: anyone who has it can manage the rooftop's promotions.
Images are either already saved in Spyne or public links to PNG or JPG files.

Base URL and headers

Every path starts with https://api.spyne.ai/api/pv1. Send these headers on every call:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The key decides the rooftop, so you never send rooftop or enterprise ids. See Authentication.

Response shape

Every response is JSON in the same shape:

{ "success": true, "statusCode": 200, "message": "…", "data": { } }

{ "success": false, "statusCode": 400, "code": "VEHICLE_NOT_FOUND", "message": "…", "data": { "notFound": ["NOT-A-VIN"] } }

Check success first. On an error, decide what to do from code (every code); message is for people and can change.

Rate limits

Per rooftop: 30 changes a minute (create, dry run, change status, delete, add an image) and 120 reads a minute. Going over returns 429 RATE_LIMITED; wait the seconds in the Retry-After header, then retry.

Statuses

Status	Meaning
`draft`	Saved, not live.
`scheduled`	Goes live by itself on its start date.
`active`	Live on the vehicles' photos.
`paused`	Stopped for now; can be resumed.
`completed`	Ended for good.

Words you'll see

Word	Meaning
Banner	An image laid on top of a photo, such as a price strip or an offer badge.
Billboard	A full image added as its own slide among the photos, such as an offer card.
Asset	A banner or billboard saved in Spyne. Its `id` is sent as `assetId`.
Dry run	A test request: everything is checked and nothing is created.
Priority	Decides which promotion shows when a vehicle is in more than one.