{"openapi":"3.1.0","info":{"title":"ListMint Listing-Writing API","version":"1.0.1","description":"Separate listing-writing API on https://listmint.pages.dev. It does not prepare supplier CSVs; its credits cannot unlock supplier exports. Listing-writing paid packs are disabled: check /api/v1/plans for generation and checkout readiness. For free CSV checks and the $9 supplier browser workflow, see /agents and /agent-capabilities.json. Creating checkout never charges a payment method."},"servers":[{"url":"https://listmint.pages.dev","description":"ListMint production. These operations are for listing-writing only."}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/plans":{"get":{"operationId":"listPlans","summary":"Read pricing and current availability","security":[],"responses":{"200":{"description":"Catalog and current readiness.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plans"}}}},"503":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account":{"get":{"operationId":"getAccount","summary":"Read account balance and this key’s allowance","description":"Requires read. Initializes the account’s single trial credit if necessary.","responses":{"200":{"description":"Current credits and permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key can retry."}}},"503":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/listings":{"post":{"operationId":"generateListing","summary":"Generate and save one listing pack","description":"Requires listings:write. Costs one credit on success, counts against the key’s lifetime generation limit, and returns the same result without another debit on identical retries. Only one active generation per account. Allow at least 70 seconds for the response. After a timeout, GET the listing ID or repeat the identical POST with the same Idempotency-Key. A refunded attempt needs a new UUID.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"UUID for this operation. Reuse only when retrying the same request. Listing IDs equal this UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brief"}}}},"responses":{"200":{"description":"Completed result, including on replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResult"}}}},"400":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key can retry."}}},"502":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/listings/{id}":{"get":{"operationId":"getListing","summary":"Read a listing or check generation status","description":"Requires read. The ID is the Idempotency-Key used to generate. Account ownership is enforced. Poll no faster than every 2 seconds.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listing status and current balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResult"}}}},"400":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key can retry."}}},"503":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/checkouts":{"post":{"operationId":"createCreditCheckout","summary":"Request Stripe checkout for a credit pack","description":"Requires checkouts:write. Confirm the current catalog price and payment authority first. Returns an account-bound Stripe Payment Link and a checkout ID. No card is charged by this request. Repeated requests with the same UUID reuse the checkout; a different pack with that UUID is rejected. Payment Links are reusable: complete a purchase only once, and poll this checkout before attempting another payment.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"UUID for this operation. Reuse only when retrying the same request. Listing IDs equal this UUID.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Checkout URL or its already-confirmed payment status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key can retry."}}},"503":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/checkouts/{id}":{"get":{"operationId":"getCreditCheckout","summary":"Check verified credit purchase fulfillment","description":"Requires read. Status comes from verified Stripe webhooks, never redirects or client assertions. Poll no faster than every 2 seconds. A reused Payment Link can produce multiple separate paid sessions; payment_count and credits_granted reflect all confirmed sessions associated with this checkout. Full refunds are tracked; partial refunds and disputes require operator handling.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Confirmed payments and credits granted; null checkout_url after payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key can retry."}}},"503":{"description":"Request failed; error is human-readable and code is stable for automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Listmint API key","description":"Create a scoped key at /developers while signed in. Store it in LISTMINT_API_KEY. Use HTTPS in production. Keys cannot create or revoke other keys. Never send a Listmint key to Stripe or any other host."}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","examples":["invalid_api_key","insufficient_scope","key_credit_limit","insufficient_credits","idempotency_conflict","generation_in_progress","generation_refunded","generation_failed","rate_limit","checkout_unavailable","price_mismatch","not_found"]}}},"Brief":{"type":"object","additionalProperties":false,"required":["name","details","platform","tone"],"properties":{"name":{"type":"string","minLength":2,"maxLength":160},"details":{"type":"string","minLength":20,"maxLength":4000},"audience":{"type":"string","maxLength":200,"default":""},"platform":{"type":"string","enum":["Shopify","Etsy","eBay","General store"]},"tone":{"type":"string","enum":["Warm & natural","Clear & concise","Bold & playful","Refined & premium"]}},"examples":[{"name":"Everyday linen tote","details":"100% linen tote bag. Natural oat color. 15 × 16 inches with 10-inch handles. Inner pocket. Made in small batches in Portland. Machine wash cold, air dry.","audience":"People who love simple, useful everyday objects","tone":"Warm & natural","platform":"Shopify"}]},"Listing":{"type":"object","required":["title","description","highlights","search_phrases","social_caption","review_notes"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"search_phrases":{"type":"array","items":{"type":"string"}},"social_caption":{"type":"string"},"review_notes":{"type":"array","items":{"type":"string"}}}},"ListingResult":{"type":"object","required":["id","status","listing","credits"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processing","completed","refunded"]},"listing":{"anyOf":[{"$ref":"#/components/schemas/Listing"},{"type":"null"}]},"credits":{"type":["integer","null"],"description":"Account credit balance. May be negative after a refund of credits already used."},"created_at":{"type":"string","format":"date-time"}}},"Plan":{"type":"object","required":["id","name","credits","amount_cents","currency"],"properties":{"id":{"type":"string","enum":["starter","studio"]},"name":{"type":"string"},"credits":{"type":"integer"},"amount_cents":{"type":"integer"},"currency":{"const":"usd"}}},"Plans":{"type":"object","required":["plans","platforms","generation_available","checkout_available","test_mode"],"properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"platforms":{"type":"array","items":{"type":"string"}},"generation_available":{"type":"boolean"},"checkout_available":{"type":"boolean"},"test_mode":{"type":"boolean"},"payment_flow":{"const":"stripe_hosted_checkout"},"documentation":{"type":"string"},"openapi":{"type":"string"}}},"Account":{"type":"object","required":["credits","generation_available","checkout_available","test_mode","key"],"properties":{"credits":{"type":"integer"},"generation_available":{"type":"boolean"},"checkout_available":{"type":"boolean"},"test_mode":{"type":"boolean"},"key":{"type":"object","required":["id","scopes","expires_at","generation_limit","generations_used","generations_remaining"],"properties":{"id":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"},"generation_limit":{"type":"integer"},"generations_used":{"type":"integer"},"generations_remaining":{"type":"integer"}}}}},"CheckoutRequest":{"type":"object","additionalProperties":false,"required":["pack","expected_amount_cents","currency"],"properties":{"pack":{"type":"string","enum":["starter","studio"]},"expected_amount_cents":{"type":"integer","minimum":1,"description":"Must equal the selected plan’s current amount_cents."},"currency":{"const":"usd"}},"examples":[{"pack":"starter","expected_amount_cents":900,"currency":"usd"}]},"Checkout":{"type":"object","required":["id","pack","status","checkout_url","payment_count","credits_granted","test_mode","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"pack":{"type":"string","enum":["starter","studio"]},"status":{"type":"string","enum":["awaiting_payment","paid","refunded","partially_refunded"]},"checkout_url":{"type":["string","null"],"description":"Stripe-hosted URL for an unpaid checkout while purchasing is enabled. Never attach your Listmint bearer key."},"payment_count":{"type":"integer","minimum":0},"credits_granted":{"type":"integer","minimum":0,"description":"Total credits from this checkout minus credits reversed by full refunds; not the account balance."},"test_mode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}