{"openapi":"3.1.0","info":{"title":"Clipping.Zone Marketplace API","version":"1.0.0","summary":"Two-sided clipping marketplace: brands fund campaigns, clippers submit posts.","description":"Clipping.Zone is a marketplace connecting brands (buyers) and independent clippers (sellers).\n\nIt is not the brand, not the employer of clippers, and not an advertising agency.\n\nBrands pay a 5% platform fee on campaign spend. Clipper-facing rates per 1,000 verified views are paid in full — the fee is not taken out of the rate.\n\nNew campaigns start as `draft` until the budget (plus the platform fee) is funded through Stripe Checkout (`POST /api/v1/campaigns/{id}/checkout`). Until `STRIPE_SECRET_KEY` is a test-mode key, that funding path is blocked with a clear 503 — it does not fall back to a payment link. Clip verification stays human.\n\nAgents acting for a brand authenticate with an API key. Registering a brand does not require an email inbox.","contact":{"email":"support@clipping.zone","url":"https://clipping.zone/llms.txt"}},"servers":[{"url":"https://clipping.zone","description":"Clipping.Zone"}],"tags":[{"name":"Discovery","description":"Public docs for agents."},{"name":"Brands","description":"Register a brand and inspect the authenticated brand."},{"name":"Campaigns","description":"Create draft campaigns and list the brand's campaigns."},{"name":"Submissions","description":"List clips and approve or reject them."}],"paths":{"/llms.txt":{"get":{"tags":["Discovery"],"summary":"Agent instructions (plain text)","operationId":"getLlmsTxt","security":[],"responses":{"200":{"description":"Plain-text marketplace + API guide.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"This OpenAPI document","operationId":"getOpenApi","security":[],"responses":{"200":{"description":"OpenAPI 3.1 spec."}}}},"/api/v1":{"get":{"tags":["Discovery"],"summary":"API index","operationId":"getApiIndex","security":[],"responses":{"200":{"description":"Links to docs and endpoints."}}}},"/api/v1/brands":{"post":{"tags":["Brands"],"summary":"Register a brand and issue an API key","description":"Creates a brand profile and returns a `cz_live_…` API key. No email inbox or magic link is required. The plaintext key is shown once — store it.","operationId":"registerBrand","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterBrandRequest"},"example":{"company_name":"Acme Co","contact_name":"Launch agent","email":"optional@acme.example"}}}},"responses":{"201":{"description":"Brand created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterBrandResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/api/v1/me":{"get":{"tags":["Brands"],"summary":"The authenticated brand","operationId":"getMe","responses":{"200":{"description":"Brand profile + key prefix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/api/v1/api-keys":{"post":{"tags":["Brands"],"summary":"Issue an additional API key","description":"Existing keys stay valid. The new plaintext is shown once.","operationId":"createApiKey","responses":{"201":{"description":"New key issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyIssued"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/api/v1/campaigns":{"get":{"tags":["Campaigns"],"summary":"List this brand's campaigns (including drafts)","operationId":"listCampaigns","responses":{"200":{"description":"Campaigns newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"}}}},"401":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Campaigns"],"summary":"Create a draft campaign","description":"Creates a campaign in `draft`. Drafts are not listed on the public Discover page. They go live after the brand funds the budget plus the 5% platform fee through Stripe Checkout.","operationId":"createCampaign","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignRequest"},"example":{"title":"Acme — summer launch","niche":"Energy · Lifestyle","rate_per_1k":1.8,"budget_cap":10000,"brief":"Cut high-energy clips from the launch film. Hook in the first second.","rules":"## Do\n- Tag @acme and #ad\n\n## Don't\n- No third-party watermarks","source_content_url":"https://example.com/source","eligible_platforms":["tiktok","instagram","youtube"],"ends_at":"2026-12-31"}}}},"responses":{"201":{"description":"Draft campaign created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/api/v1/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get one of this brand's campaigns","operationId":"getCampaign","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEnvelope"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/campaigns/{id}/checkout":{"post":{"tags":["Campaigns"],"summary":"Create a Stripe Checkout Session to fund a draft","description":"Charges the brand `brand_total_cents` (budget cap + disclosed 5% platform fee) on the platform account. On `checkout.session.completed` the campaign becomes `live`. Returns 503 with a clear message if `STRIPE_SECRET_KEY` is unset — there is no payment-link fallback. Test-mode keys only.","operationId":"createCampaignCheckout","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Checkout Session URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutEnvelope"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/v1/campaigns/{id}/submissions":{"get":{"tags":["Submissions"],"summary":"List submissions on a campaign","operationId":"listSubmissions","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Submissions oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionList"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/submissions/{id}/approve":{"post":{"tags":["Submissions"],"summary":"Approve a pending submission","description":"Starts view accrual. During the pilot, verification is human — this is the marketplace function, whether the human is you or the operator.","operationId":"approveSubmission","parameters":[{"$ref":"#/components/parameters/SubmissionId"}],"responses":{"200":{"description":"Approved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionEnvelope"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/api/v1/submissions/{id}/reject":{"post":{"tags":["Submissions"],"summary":"Reject a submission with a reason code","operationId":"rejectSubmission","parameters":[{"$ref":"#/components/parameters/SubmissionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectSubmissionRequest"},"example":{"reason":"off_brief"}}}},"responses":{"200":{"description":"Rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"BrandApiKey":{"type":"http","scheme":"bearer","bearerFormat":"cz_live_","description":"API key issued at POST /api/v1/brands. Send as `Authorization: Bearer cz_live_…`."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"SubmissionId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"RegisterBrandRequest":{"type":"object","required":["company_name"],"properties":{"company_name":{"type":"string","minLength":1,"maxLength":200},"contact_name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","description":"Optional contact email. Not used for login; agents can omit it."}}},"RegisterBrandResponse":{"type":"object","properties":{"brand":{"$ref":"#/components/schemas/Brand"},"api_key":{"type":"string","description":"Plaintext key, shown once."},"api_key_prefix":{"type":"string"}}},"Brand":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"company_name":{"type":"string"},"contact_name":{"type":["string","null"]},"email":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"MeResponse":{"type":"object","properties":{"brand":{"$ref":"#/components/schemas/Brand"},"api_key_prefix":{"type":"string"}}},"ApiKeyIssued":{"type":"object","properties":{"api_key":{"type":"string"},"api_key_prefix":{"type":"string"}}},"CreateCampaignRequest":{"type":"object","required":["title","eligible_platforms"],"properties":{"brand_name":{"type":"string","description":"Defaults to the brand's company_name."},"title":{"type":"string"},"niche":{"type":"string"},"slug":{"type":"string","description":"Optional. Auto-generated from title if omitted."},"rate_per_1k_cents":{"type":"integer","description":"Integer cents. Alternative: rate_per_1k in dollars."},"rate_per_1k":{"type":"number","description":"Dollars per 1,000 verified views, e.g. 1.80."},"budget_cap_cents":{"type":"integer"},"budget_cap":{"type":"number","description":"Dollars, e.g. 10000."},"brief":{"type":"string"},"rules":{"type":"string"},"source_content_url":{"type":"string","format":"uri"},"eligible_platforms":{"type":"array","items":{"type":"string","enum":["tiktok","instagram","youtube","x","facebook","twitch","snapchat","linkedin"]}},"ends_at":{"type":"string","description":"ISO date (YYYY-MM-DD) or datetime."}}},"Campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"brand_name":{"type":"string"},"title":{"type":"string"},"niche":{"type":["string","null"]},"status":{"type":"string","enum":["draft","live","ended"]},"rate_per_1k_cents":{"type":"integer"},"budget_cap_cents":{"type":"integer"},"platform_fee_bps":{"type":"integer","example":500},"platform_fee_percent":{"type":"number","example":5},"platform_fee_cents":{"type":"integer"},"brand_total_cents":{"type":"integer","description":"Budget cap + platform fee."},"brief":{"type":"string"},"rules":{"type":"string"},"source_content_url":{"type":["string","null"]},"eligible_platforms":{"type":"array","items":{"type":"string"}},"ends_at":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"funding":{"type":"object"}}},"CheckoutEnvelope":{"type":"object","properties":{"checkout":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"session_id":{"type":"string"},"brand_total_cents":{"type":"integer"},"platform_fee_cents":{"type":"integer"}}},"campaign":{"$ref":"#/components/schemas/Campaign"}}},"CampaignEnvelope":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}}},"CampaignList":{"type":"object","properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}},"Submission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid"},"post_url":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string","enum":["pending","verified","rejected","paused"]},"rejection_reason":{"type":["string","null"]},"verified_at":{"type":["string","null"]},"latest_view_count":{"type":"integer"},"clipper":{"type":"object"}}},"SubmissionEnvelope":{"type":"object","properties":{"submission":{"$ref":"#/components/schemas/Submission"}}},"SubmissionList":{"type":"object","properties":{"submissions":{"type":"array","items":{"$ref":"#/components/schemas/Submission"}}}},"RejectSubmissionRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["off_brief","watermarked","reposted","misleading_caption","account_mismatch","private_or_deleted","ineligible_platform"],"description":"Shown to the clipper verbatim."}}},"ErrorBody":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}},"security":[{"BrandApiKey":[]}]}