Developers
PropulSell API for developers
The PropulSell Public API exposes the same generation pipelines as the Studio dashboard over HTTPS and JSON. It is available to Expert Pro accounts and draws from the same credit pool as the dashboard.
Machine-readable spec
The OpenAPI 3.1 document is published at /openapi.json (JSON) and /openapi.yaml (YAML). Every operation has a unique operationId, a description, typed parameters and response schemas. Interactive reference: /api-docs.
Authentication
Create an API key in Studio > Settings > API Keys and send it as a bearer token: Authorization: Bearer psl_live_<key>. Keys only work while the owning account is on the Expert Pro plan.
Endpoints
Base URL: https://propulsell.com/api/v1
- GET /me (getMe): plan and key metadata.
- GET /credits (getCredits): remaining credit balance.
- POST /ad-crafter (createAdCrafterListing): synchronous; photo in, listing and image out.
- POST /beautifier (createBeautifierImage): synchronous; clean up a product photo.
- POST /recoloration (createRecoloration): synchronous; recolor a garment.
- POST /photoshoots (createPhotoshoot): asynchronous; returns 202 and a job_id.
- POST /video (createVideo): asynchronous; returns 202 and a job_id.
- POST /models (createModel): asynchronous; returns 202 and a job_id.
- GET /jobs/{id} (getJob): poll an asynchronous job until status is completed or failed.
Errors
Every response, including errors and unknown /api paths, is JSON in the shape {"data": ..., "error": ...}. An error carries a machine-readable code (invalid_request, unauthorized, insufficient_credits, forbidden, not_found, rate_limited, internal_error, upstream_error), a message, and a hint that says how to resolve it.
Rate limits
Each key is limited to 60 requests per minute by default. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; a 429 response also carries Retry-After (seconds).
Versioning and deprecation
The major version is in the URL (/api/v1) and echoed in the API-Version response header. Within v1 we only add optional fields and endpoints. A deprecated endpoint answers with a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 6 months before removal. No endpoint is deprecated today.
Command-line client
PropulSell CLI (npm package propulsell-cli) wraps the API for scripts and agents: npx propulsell-cli credits, npx propulsell-cli job <id>, or pipe a JSON body into npx propulsell-cli post beautifier. Set PROPULSELL_API_KEY to your API key.
Example request
curl https://propulsell.com/api/v1/credits \
-H "Authorization: Bearer psl_live_<your_key>"
# 200 OK
# RateLimit-Limit: 60
# RateLimit-Remaining: 59
# RateLimit-Reset: 42
# {"data":{"credits_remaining":420},"error":null}