{"openapi":"3.1.0","info":{"title":"Leaderbored API","version":"1.0.0","description":"Distinctive advertising ideas for creative or inspiration agents. Powered by Flint from Springboards, grounded in Australian category patterns. Browse patterns and retrieve saved ideas free. Patterns come from monthly Australian category exports, not live Meta scraping. Observation counts are not ad volumes or measured market share. Buy 10 idea credits for A$1.00 (AUD), a one-time purchase. Each saved idea costs 1 credit (A$0.10) and includes a concept, a suggested execution and why it differs from category patterns. A human approves and completes Stripe checkout; agents spend authorized credits. Ideas are generated on demand and never resold on Leaderbored. Originality outside the marketplace, copyright exclusivity and campaign results are not guaranteed. See /agents.md for payment, receipt privacy and safe retries."},"servers":[{"url":"/api","description":"Base API path"}],"tags":[{"name":"health","description":"Health operations"},{"name":"marketplace","description":"Categories, conventions, and monthly trend summaries"},{"name":"checkout","description":"Stripe credit-pack checkout and confirmation"},{"name":"ideas","description":"Generate and retrieve one-time category ideas"},{"name":"agents","description":"Machine-readable marketplace discovery"}],"paths":{"/healthz":{"get":{"operationId":"healthCheck","tags":["health"],"summary":"Health check","description":"Returns server health status","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}},"/categories":{"get":{"operationId":"listCategories","tags":["marketplace"],"summary":"List Australian advertising categories","responses":{"200":{"description":"Current category convention snapshots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}}}}},"/marketplace/stats":{"get":{"operationId":"getMarketplaceStats","tags":["marketplace"],"summary":"Get marketplace and import coverage","responses":{"200":{"description":"Summary based on stored monthly imports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceStats"}}}}}}},"/marketplace/trends":{"get":{"operationId":"getMarketplaceTrends","tags":["marketplace"],"summary":"Compare recurring themes across monthly imports","parameters":[{"name":"months","in":"query","required":false,"schema":{"type":"integer","minimum":2,"maximum":12,"default":6}}],"responses":{"200":{"description":"Monthly theme counts grouped by category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceTrends"}}}}}}},"/marketplace/imports":{"get":{"operationId":"listMonthlyImports","tags":["marketplace"],"summary":"List retained monthly category imports","responses":{"200":{"description":"Import history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthlyImportList"}}}}}}},"/checkout/sessions":{"post":{"operationId":"createCheckoutSession","tags":["checkout"],"summary":"Create an approved Stripe checkout for 10 idea credits at A$1.00 (AUD)","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutPurchaseInput"}}}},"description":"Returns sessionId and checkoutUrl. Creating checkout does not charge a card; a human must approve and complete payment on Stripe. The sessionId is a private access credential for the pack, not an email receipt. Sessions starting with cs_test_ are test mode, not live purchases.","responses":{"201":{"description":"Stripe checkout session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}}}}},"/checkout/sessions/{sessionId}":{"get":{"deprecated":true,"operationId":"getCheckoutSession","tags":["checkout"],"summary":"Verify payment and retrieve remaining idea credits","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout status and credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatus"}}}},"404":{"description":"Checkout session not found"}}}},"/checkout/sessions/status":{"post":{"operationId":"checkCheckoutStatus","tags":["checkout"],"summary":"Verify payment privately using a receipt in the request body","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutReceiptInput"}}}},"responses":{"200":{"description":"Checkout status and remaining credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatus"}}}}}}},"/ideas/claim/async":{"post":{"operationId":"startIdeaClaim","tags":["ideas"],"summary":"Start or poll a durable idea claim using the same requestId","description":"Preferred transport. Returns 202 while generation runs, then 201 with the saved idea. Repeat the identical body every two seconds; never generate a new requestId to poll. One credit is spent only after saving. An interrupted client can recover through history or repeat the same request.","parameters":[{"in":"header","name":"X-Leaderbored-Poll","schema":{"type":"string","enum":["true"]},"description":"Send true on polls so a failed generation is reported rather than restarted."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaClaimInput"}}}},"responses":{"201":{"description":"Saved idea or idempotent recovery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Idea"}}}},"202":{"description":"Still generating; repeat the same body after pollAfterMs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimPending"}}}},"400":{"description":"Unknown categoryId; validCategoryIds returned. No credit spent."},"402":{"description":"No paid credits remain"},"409":{"description":"This requestId belongs to another category"},"502":{"description":"Generation failed; retry the same requestId. No credit spent unless an idea was saved."}}}},"/ideas/claim":{"post":{"operationId":"claimIdea","tags":["ideas"],"summary":"Generate and save a Flint-powered advertising idea for 1 paid credit","description":"Legacy synchronous transport; prefer /ideas/claim/async to avoid long public requests. Requires categoryId, the private checkoutSessionId and a UUID requestId. Allow 120 seconds. Spend one credit only after saving. For an interrupted request, retry the SAME requestId with the same category and receipt to recover without another debit. Each idea is never resold on Leaderbored; external originality is not guaranteed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaClaimInput"}}}},"responses":{"201":{"description":"Saved idea containing concept, execution and distinction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Idea"}}}},"400":{"description":"Unknown categoryId; validCategoryIds returned. No credit spent."},"402":{"description":"No paid credits remain"},"404":{"description":"Checkout session not found"},"503":{"description":"Flint generation is not configured"}}}},"/ideas/retrieve":{"post":{"operationId":"retrieveIdea","tags":["ideas"],"summary":"Retrieve a saved idea for free using its private checkout receipt","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaLookupInput"}}}},"responses":{"200":{"description":"The purchased idea","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Idea"}}}},"404":{"description":"Idea not found for this checkout session"}}}},"/ideas/history":{"post":{"operationId":"listPurchasedIdeas","tags":["ideas"],"summary":"List saved ideas for free using their owning private checkout receipt","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutReceiptInput"}}}},"responses":{"200":{"description":"Purchased ideas, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaList"}}}}}}},"/agent/catalog":{"get":{"operationId":"getAgentCatalog","tags":["agents"],"summary":"Read the agent marketplace catalog and purchase protocol","responses":{"200":{"description":"Machine-readable catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCatalog"}}}}}}},"/agent/guide":{"get":{"operationId":"getAgentGuide","tags":["agents"],"summary":"Read the agent integration guide","responses":{"200":{"description":"Agent guide in Markdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGuide"}}}}}}},"/agent/catalog.md":{"get":{"operationId":"getAgentMarkdown","tags":["agents"],"summary":"Read the plain Markdown agent purchase protocol","responses":{"200":{"description":"Human and agent-readable integration protocol","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/agent/tools":{"get":{"operationId":"getAgentTools","tags":["agents"],"summary":"Discover the shared MCP and WebMCP tool definitions","responses":{"200":{"description":"Tool names, JSON input schemas, and safety annotations","content":{"application/json":{"schema":{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/agent/tools/call":{"post":{"operationId":"callAgentTool","tags":["agents"],"summary":"Execute a discovered tool using the same validated marketplace operations","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentToolRequest"}}}},"responses":{"200":{"description":"MCP-compatible content and structuredContent; inspect isError","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid envelope"}}}},"/agent/mcp":{"post":{"operationId":"handleAgentMcp","tags":["agents"],"summary":"Stateless MCP Streamable HTTP transport","description":"Supports initialize, tools/list, tools/call, resources/list, resources/read, and notifications. Send Accept application/json and text/event-stream. Human-approved Stripe payment is required before claiming.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpEnvelope"}}}},"responses":{"200":{"description":"MCP JSON-RPC response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Notification accepted"}}}},"/agent/openapi.json":{"get":{"operationId":"getAgentOpenApi","tags":["agents"],"summary":"Public OpenAPI contract for importing the HTTP API into agents","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/categories.md":{"get":{"operationId":"getCategoryMarkdown","tags":["agents"],"summary":"Live category, theme, and keyword data in plain Markdown","responses":{"200":{"description":"Current imported categories","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ClaimPending":{"type":"object","required":["status","requestId","categoryId","pollAfterMs","message"],"properties":{"status":{"type":"string","enum":["pending"]},"requestId":{"type":"string"},"categoryId":{"type":"string"},"pollAfterMs":{"type":"integer"},"message":{"type":"string"}}},"CheckoutPurchaseInput":{"type":"object","properties":{"categoryId":{"type":"string"}}},"AgentToolRequest":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","maxLength":30},"arguments":{"type":"object","additionalProperties":true}}},"McpEnvelope":{"type":"object","additionalProperties":true},"HealthStatus":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]},"CategoryPattern":{"type":"object","required":["theme","keywords","frequency"],"properties":{"theme":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"frequency":{"type":"integer","minimum":0,"description":"Row count; when the category has sampleData true, this counts sample rows, not imported research or ad volume."},"countLabel":{"type":"string","description":"Human-readable count, for example 1 sample row."},"change":{"type":["integer","null"]}}},"Category":{"type":"object","required":["id","name","description","source","patterns"],"properties":{"sampleData":{"type":"boolean"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"latestMonth":{"type":["string","null"]},"source":{"type":"string","enum":["illustrative","monthly_import"]},"patterns":{"type":"array","items":{"$ref":"#/components/schemas/CategoryPattern"}}}},"CategoryList":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"MarketplaceStats":{"type":"object","required":["categoryCount","importCount","latestMonth","totalPatterns","source"],"properties":{"sampleData":{"type":"boolean"},"categoryCount":{"type":"integer"},"importCount":{"type":"integer"},"latestMonth":{"type":["string","null"]},"totalPatterns":{"type":"integer"},"source":{"type":"string","enum":["illustrative","monthly_import","mixed","unavailable"]}}},"MonthlyImport":{"type":"object","required":["month","importedAt","categoriesUpdated","patternCount","source"],"properties":{"month":{"type":"string"},"importedAt":{"type":"string","format":"date-time"},"categoriesUpdated":{"type":"integer"},"patternCount":{"type":"integer"},"source":{"type":"string","enum":["illustrative","monthly_import"]}}},"MonthlyImportList":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyImport"}},"MonthlyThemePoint":{"type":"object","required":["month","count"],"properties":{"month":{"type":"string"},"count":{"type":["integer","null"],"minimum":0}}},"ThemeTrend":{"type":"object","required":["theme","months"],"properties":{"theme":{"type":"string"},"months":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyThemePoint"}}}},"CategoryTrend":{"type":"object","required":["categoryId","categoryName","themes"],"properties":{"categoryId":{"type":"string"},"categoryName":{"type":"string"},"themes":{"type":"array","items":{"$ref":"#/components/schemas/ThemeTrend"}}}},"MarketplaceTrends":{"type":"object","required":["months","categories","source"],"properties":{"sampleData":{"type":"boolean"},"comparisonAvailable":{"type":"boolean","description":"True only when at least two actual imported months are present."},"coverageMessage":{"type":"string"},"months":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryTrend"}},"source":{"type":"string","enum":["illustrative","monthly_import","mixed","unavailable"]}}},"CheckoutSession":{"type":"object","required":["sessionId","checkoutUrl","amountMinor","currency","creditQuantity","unitPriceMinor"],"properties":{"sessionId":{"type":"string","description":"Private Stripe Checkout session ID. Use as checkoutSessionId for credits and recovery. Not an email receipt or invoice number; share only with your authorized agent."},"checkoutUrl":{"type":"string","format":"uri"},"amountMinor":{"type":"integer","const":100},"currency":{"type":"string","const":"aud"},"creditQuantity":{"type":"integer","const":10},"unitPriceMinor":{"type":"integer","const":10}}},"CheckoutStatus":{"type":"object","required":["sessionId","status","creditsGranted","creditsRemaining"],"properties":{"sessionId":{"type":"string"},"status":{"type":"string","enum":["open","paid","expired","unpaid"]},"creditsGranted":{"type":"boolean"},"creditsRemaining":{"type":"integer","minimum":0}}},"IdeaClaimInput":{"type":"object","required":["categoryId","checkoutSessionId","requestId"],"properties":{"categoryId":{"type":"string"},"checkoutSessionId":{"type":"string"},"requestId":{"type":"string","format":"uuid","description":"Generate a fresh UUID for each NEW idea. Retry an interrupted request with the SAME UUID, category and receipt to recover a saved idea without another credit debit. Do not reuse for a different category."}}},"IdeaLookupInput":{"type":"object","required":["ideaId","checkoutSessionId"],"properties":{"ideaId":{"type":"string"},"checkoutSessionId":{"type":"string"}}},"CheckoutReceiptInput":{"type":"object","required":["checkoutSessionId"],"properties":{"checkoutSessionId":{"type":"string","pattern":"^cs_[a-zA-Z0-9_]+$","maxLength":256}}},"IdeaList":{"type":"array","items":{"$ref":"#/components/schemas/Idea"}},"Idea":{"type":"object","required":["id","categoryId","categoryName","title","concept","execution","distinction","createdAt"],"properties":{"distinctionThemes":{"type":"array","description":"New ideas cite 1–3 exact selected-category theme names in distinction. Older ideas may return an empty array.","maxItems":3,"items":{"type":"string"}},"id":{"type":"string"},"categoryId":{"type":"string"},"categoryName":{"type":"string"},"title":{"type":"string"},"concept":{"type":"string","description":"The advertising idea, a creative starting point rather than a finished ad."},"execution":{"type":"string","description":"A suggested creative execution."},"distinction":{"type":"string","description":"How the idea differs from the selected category patterns."},"createdAt":{"type":"string","format":"date-time"}}},"AgentCatalog":{"type":"object","required":["name","description","currency","packPriceMinor","packCredits","ideaPriceMinor","endpoints"],"properties":{"sampleData":{"type":"boolean"},"canPurchase":{"type":"boolean","description":"False when no category has patterns. Existing idea retrieval remains available."},"message":{"type":"string"},"provenance":{"type":"string"},"categories":{"type":"array","items":{"type":"object","required":["id","name","latestMonth","source","themeCount"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"latestMonth":{"type":["string","null"]},"source":{"type":"string","enum":["illustrative","monthly_import"]},"themeCount":{"type":"integer"}}}},"name":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string"},"packPriceMinor":{"type":"integer"},"packCredits":{"type":"integer"},"ideaPriceMinor":{"type":"integer"},"endpoints":{"type":"array","items":{"type":"string"}}}},"AgentGuide":{"type":"object","required":["markdown"],"properties":{"markdown":{"type":"string"}}}}}}