Developers / Madly

Build with Madly.

Create ad sets and carousels from your own code. Calls use your workspace's credits, and nothing is published to ad platforms.

Quick start

Create a key. In Madly, open Settings, then API keys, and choose Create key. Only admins can. Copy the key; it is shown once.
Add a product from its page.

curl https://admadly.com/api/v1/products \
  -H "Authorization: Bearer mad_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/shop/candle"}'

Create an ad set with the product's id. You get an id back straight away.

curl https://admadly.com/api/v1/ad-sets \
  -H "Authorization: Bearer mad_live_your_key" \
  -H "Idempotency-Key: first-candle-ads" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "<id from the last step>"}'

Check the ad set about once every 20 seconds until ready is true. It usually takes about a minute.

curl https://admadly.com/api/v1/ad-sets/<id> \
  -H "Authorization: Bearer mad_live_your_key"

Authentication

Send your key as a bearer token on every request: Authorization: Bearer your-key.

A key belongs to one workspace and can only reach that workspace's products, ad sets and credits. Revoke it in Settings at any time and it stops working at once. Keep keys out of web pages and public code.

Endpoints

All paths start with https://admadly.com/api/v1.

Method	Path	What it does
GET	/products	List products
POST	/products	Add a product from a URL
POST	/ad-sets	Create an ad set
GET	/ad-sets/{id}	Get an ad set
POST	/idea-carousels	Create an idea carousel
GET	/idea-carousels/{id}	Get an idea carousel
GET	/credits	Get credits

Errors

Failed calls return a status code and a body like this.

{ "error": { "code": "invalid_request", "message": "Give a product_id from listProducts." } }

Status	Code	Meaning
400	invalid_request	Something in the request is missing or not valid.
401	unauthenticated	The key is missing, wrong or revoked.
402	insufficient_credits	The workspace does not have enough credits.
403	forbidden	The key cannot do this in its workspace.
404	not_found	There is nothing with that id in the workspace.
409	idempotency_in_progress	A request with the same Idempotency-Key is still running.
422	idempotency_key_reused	That Idempotency-Key was used with a different request.
429	rate_limited	Too many requests. Wait for the time in Retry-After.

Retrying safely

Add an Idempotency-Key header to any POST. Repeat the same request with the same key and you get the first answer back, with no second product, ad set or charge. Use 8 to 128 letters, numbers, dashes or underscores. Keys are remembered for 24 hours.

Rate limits

Each key can make 60 requests a minute, and 10 of those can be calls that create something. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the allowance refills). Past the limit you get a 429 with a Retry-After header.

Credits

API calls use the same credits as the app, from the workspace the key belongs to. Credits are charged as images finish. Check the balance with Get credits, and buy more in Settings under Billing. When credits run out, creating calls return 402.

OpenAPI file

Import the full description into your tools or code generator.

https://admadly.com/api/v1/openapi.json