# Listmint Agent API

> Generate product-copy drafts and request account-bound credit purchases through Stripe hosted checkout.

ListMint is live at https://listmint.pages.dev. This is the separate listing-writing API; its paid packs are disabled. Read /api/v1/plans for runtime availability. Supplier CSV preparation costs $9 per file through a signed-in browser workflow and uses separate credits. See [agent capabilities](/agents) and [public capability JSON](/agent-capabilities.json). No supplier bearer-key API is available.

## Getting started

1. Sign in with a passkey at /developers and create a named key with an expiry date, permissions, and lifetime generation allowance. The full key is shown once. Save it in your agent's secret manager as LISTMINT_API_KEY.
2. Set your base URL to https://listmint.pages.dev. Production requests must use HTTPS. Sign-in and scoped API keys protect account access.
3. Read [OpenAPI](/openapi.json) for the exact request and response schemas, [plans](/api/v1/plans) for pricing and readiness, and GET /api/v1/account with the bearer key for available credits.

## Authentication and permissions

Send Authorization: Bearer followed by the Listmint key. Keys are accepted only in that header. Browser cookies, URL parameters, and an OpenAI or Stripe key cannot authorize the agent API.

Every key has read access to its owner's account, known listing IDs, and checkout status. listings:write permits generation; checkouts:write permits creating a hosted checkout. Keys cannot mint or revoke keys. Manage keys only through the signed-in browser page.

Keys expire in 1–90 days. At most 10 keys can be active per account. Each key allows 60 authorized API requests per minute. A 429 response includes Retry-After in seconds. Poll no faster than every 2 seconds. Revoking a key blocks new calls but does not cancel a generation already in progress.

The lifetime generation allowance applies across the key's successful and currently reserved generations. Failed or expired attempts are returned. Replaying an already-completed request uses no additional allowance. Buying credits never raises the key's allowance; the owner must issue a replacement key to authorize more work.

## Generate a listing

POST /api/v1/listings requires Content-Type: application/json and an Idempotency-Key UUID header. The body contains name, details, platform, tone, and optional audience. Supported platforms: Shopify, Etsy, eBay, General store. Supported tones: Warm & natural, Clear & concise, Bold & playful, Refined & premium.

One successful generation uses one account credit. The response includes id, status, listing, and remaining credits. The id is the Idempotency-Key UUID. Results contain title, description, highlights, search_phrases, social_caption, and review_notes. Review the result before publishing; Listmint does not publish to a marketplace.

There is one active generation per account across browser and agent requests. Allow at least 70 seconds for a POST response. If the connection drops, GET /api/v1/listings/{id} or retry the identical POST with the same UUID. Changing the product brief under that UUID returns 409 idempotency_conflict. A processing job returns 409 generation_in_progress on repeated POST; GET returns status processing. Stale jobs are refunded after three minutes when the account or listing is next read or another generation is attempted. A refunded attempt requires a new UUID.

## Listing-writing credit checkout (currently disabled)

Read /api/v1/plans and confirm the user's payment authority. Prices: Starter USD 9.00 for 30 credits; Studio USD 19.00 for 100 credits. These are one-time packs.

POST /api/v1/checkouts with a new Idempotency-Key UUID and JSON containing pack, expected_amount_cents, and currency: usd. The expected amount must match the catalog. The server binds the checkout to the key owner's account. Reusing this UUID returns the same checkout; changing its pack returns 409.

This request returns a checkout_url and does not charge a card. The customer or their authorized payment agent completes payment at that Stripe URL. Listmint does not accept card details, shared payment tokens, or off-session charge requests. Never send the Listmint key to Stripe. Payment Links can be paid more than once: complete only the intended purchase and check its status before retrying a payment.

Poll GET /api/v1/checkouts/{id}. Credits are granted only by signature-verified Stripe webhooks for paid sessions. An unpaid or delayed payment remains awaiting_payment until confirmation. A success redirect is not proof of payment. Paid checkouts return checkout_url: null to discourage a second purchase. Replay of a payment event cannot grant the same session twice. Full refunds reverse their pack credits; partial refunds and disputes require operator handling.

Status paid means credits_granted were confirmed for this checkout; GET /api/v1/account reports the current spendable balance. All keys for one account share its balance. Test-mode payments never move real money. Checkout returns 503 checkout_unavailable while purchasing is disabled.

## Errors and retries

Errors return an error message and a stable code. 400: invalid input or missing UUID. 401: invalid, expired, or revoked key. 403: insufficient_scope or key_credit_limit. 402: insufficient_credits. 404: unknown or another account's resource. 409: conflicting request, current generation, refunded attempt, or price mismatch. 413: body too large. 415: JSON required. 429: request limit. 502: generation failed and its credit returned. 503: service or checkout unavailable.

Keep a durable record of operation UUIDs, checkout IDs, and listing IDs. Never retry a payment blindly or substitute a new generation UUID after a network timeout without checking the original operation.