{"openapi":"3.1.0","info":{"title":"CloutOps Agent API","version":"0.1.0","description":"OpenAPI contract for AI assistants to discover inventory, draft media plans, prepare route/quote recommendations, submit briefs, and request approval-gated actions."},"servers":[{"url":"https://client.cloutos.com"}],"x-cloutops-tools":[{"name":"search_audience_supply","method":"GET","path":"/api/inventory","category":"supply","workflowStage":"audience_route","description":"Search public CloutOps audience supply by niche, audience, campaign goal, and format. Results are usable supply examples, not guaranteed booked placements.","returns":["example inventory pages","audience/niche signals","modeled supply metrics"],"approvalRequired":false},{"name":"create_campaign","method":"POST","path":"/api/agent/campaigns","category":"campaign","workflowStage":"campaign_intake","description":"Create a client campaign intake through an org-scoped agent token. Drafts route, starter creative variants, approval gates, ops tasks, and draft invoice without booking spend.","returns":["campaign room","intake record","starter route","starter creative variants","approval gates"],"approvalRequired":true},{"name":"update_campaign_intake","method":"PATCH","path":"/api/agent/campaigns/{campaignId}","category":"campaign","workflowStage":"campaign_intake","description":"Update non-consequential campaign intake fields. Budget changes are captured as approval requests, not applied directly.","returns":["updated campaign intake","audit/provenance context"],"approvalRequired":true},{"name":"generate_media_plan","method":"POST","path":"/api/agent/plan","category":"planning","workflowStage":"audience_route","description":"Generate a draft media route with audience pools, example pages, creative units, managed-plan risk notes, and approval gates.","returns":["audience pools","example pages","creative units","commercial estimate","approval gates"],"approvalRequired":false},{"name":"generate_media_route","method":"POST","path":"/api/agent/plan","category":"planning","workflowStage":"audience_route","description":"Generate a route-style media recommendation with modeled reach/views, sample pages, backup logic, source labels, and caveats. Does not book spend.","returns":["route recommendation","modeled numbers","backup supply","route caveats"],"approvalRequired":false},{"name":"recommend_creative_formats","method":"POST","path":"/api/agent/plan","category":"creative","workflowStage":"creative_production","description":"Recommend native creative formats, required inputs, claims/disclosure checks, and approval needs for a campaign brief.","returns":["format recommendations","required inputs","approval needs","route handoff notes"],"approvalRequired":false},{"name":"prepare_quote_request","method":"POST","path":"/api/agent/plan","category":"commercials","workflowStage":"quote_approval","description":"Prepare route-based quote assumptions for human review without accepting pricing or booking spend.","returns":["quote assumptions","commercial estimate","approval gates"],"approvalRequired":true},{"name":"create_campaign_brief","method":"POST","path":"/api/briefs","category":"lead_intake","workflowStage":"campaign_intake","description":"Create a campaign brief for ops review and follow-up planning.","returns":["lead brief","ops follow-up queue"],"approvalRequired":false},{"name":"request_page_placement","method":"POST","path":"/api/placements/request","category":"supply","workflowStage":"audience_route","description":"Request a specific page placement for ops confirmation. Availability and final pricing are not guaranteed.","returns":["placement request","ops confirmation requirement"],"approvalRequired":true},{"name":"request_specific_pages","method":"POST","path":"/api/placements/request","category":"supply","workflowStage":"audience_route","description":"Attach specific page requests to a managed plan for ops confirmation. These requests do not override route fit, availability, or final pricing.","returns":["specific page request","managed route context"],"approvalRequired":true},{"name":"get_campaign_report","method":"GET","path":"/api/agent/campaigns/{campaignId}/report","category":"reporting","workflowStage":"placement_proof_reporting","description":"Read normalized campaign reporting, provider/sync status, metric source labels, sentiment, placement metrics, creative metrics, snapshot history, and organic lift signals.","returns":["summary metrics","provider status","sync status","placement metrics","creative metrics","sentiment","organic lift"],"approvalRequired":false},{"name":"get_client_launch_plan","method":"GET","path":"/api/agent/launch-plan","category":"workspace","workflowStage":"workspace_setup","description":"Read the workspace-level client launch plan with readiness, next owner, buyer actions, risks, meeting agenda, operating rules, and links to campaign packets.","returns":["workspace readiness","buyer actions","CloutOps actions","risks","packet links"],"approvalRequired":false},{"name":"get_first_five_operating_packet","method":"GET","path":"/api/agent/first-five","category":"workspace","workflowStage":"workspace_setup","description":"Read the delivery operating packet: route dossier, creative production, supply availability, campaign room, and finance/proof readiness across the workspace.","returns":["operating readiness","buyer inputs","CloutOps outputs","approval artifacts","missing checks","campaign room links"],"approvalRequired":false},{"name":"get_route_dossier","method":"GET","path":"/api/agent/campaigns/{campaignId}/route-dossier","category":"planning","workflowStage":"quote_approval","description":"Read the exportable route approval dossier with audience rationale, page targets, backups, source labels, caveats, quote assumptions, and approval gates.","returns":["route approval dossier","modeled vs verified notes","page examples","backups","quote assumptions"],"approvalRequired":false},{"name":"get_campaign_launch_packet","method":"GET","path":"/api/agent/campaigns/{campaignId}/launch-packet","category":"campaign","workflowStage":"quote_approval","description":"Read the executive launch packet that combines route, creative production, supply/backups, campaign room state, proof/reporting, finance, approvals, and agent-safe next actions.","returns":["campaign command summary","delivery workflow state","agent-safe next actions"],"approvalRequired":false},{"name":"get_creative_production_packet","method":"GET","path":"/api/agent/campaigns/{campaignId}/creative-packet","category":"creative","workflowStage":"creative_production","description":"Read the campaign-level creative production packet with source assets, native formats, claims/disclosure needs, creative package readiness, approvals, and route handoff.","returns":["creative work order","format system","source asset state","claims/disclosures","route handoff"],"approvalRequired":false},{"name":"get_creative_template_library","method":"GET","path":"/api/agent/creative-templates","category":"creative","workflowStage":"creative_production","description":"Read the reusable creative template library for meme, news, text-over-video, and mixed-carousel packages, including required inputs, approval checks, handoff packages, and agent-safe brief fields.","returns":["template library","required inputs","production fields","approval checks","route handoff rules","agent-safe usage rules"],"approvalRequired":false},{"name":"request_creative_production","method":"POST","path":"/api/agent/campaigns/{campaignId}/creative-requests","category":"creative","workflowStage":"creative_production","description":"Create a draft native creative production request from an org-scoped agent token. Produces a draft creative packet, export spec, ops task, and audit record without approving final creative or booking spend.","returns":["draft creative variant","creative decision packet","ops production task","human approval guardrails"],"approvalRequired":true},{"name":"get_invoice_status","method":"GET","path":"/api/agent/invoices/{invoiceId}","category":"finance","workflowStage":"placement_proof_reporting","description":"Read the commercial packet for an invoice: quote/IO scope, line items, PO and signed-document context, proof evidence, payment state, makegoods, source labels, and readiness checks.","returns":["commercial packet","invoice status","quote/IO context","line items","payment records","proof evidence","makegoods"],"approvalRequired":false},{"name":"submit_approval","method":"POST","path":"/api/agent/approvals/{approvalId}","category":"approvals","workflowStage":"quote_approval","description":"Submit an agent recommendation for a route, creative variant, placement, report, or invoice approval. The approval gate is not decided until an authorized human acts.","returns":["approval recommendation","audit entry"],"approvalRequired":true},{"name":"get_approval_packet","method":"GET","path":"/api/agent/approvals/{approvalId}/packet","category":"approvals","workflowStage":"quote_approval","description":"Read the exportable approval packet with subject summary, named approvers, timing, guardrails, decision notes, and audit trail.","returns":["approval packet","subject snapshot","audit trail","guardrails"],"approvalRequired":false},{"name":"enrich_inventory_page","method":"POST","path":"/api/enrich","category":"supply","workflowStage":"audience_route","description":"Queue enrichment for profile data, captions, metrics, and classification updates.","returns":["enrichment job result","updated inventory classification when available"],"approvalRequired":true}],"x-cloutops-auth":{"current":"api_key_required","configured":true,"scopes":["agent:read","agent:plan"],"organizationScoped":true,"acceptedHeaders":["Authorization: Bearer <token>","x-cloutops-agent-key"],"productionRequirement":"Set CLOUTOPS_AGENT_API_KEY, CLOUTOPS_AGENT_SCOPES, and CLOUTOPS_AGENT_ORGANIZATION_ID before exposing stateful customer tools."},"x-cloutops-auth-note":"OpenAPI and tool discovery can be public, but stateful agent tools require a bearer token or x-cloutops-agent-key. Consequential actions still create approval requests or require a human gate.","x-cloutops-workflow":[{"id":"workspace_setup","label":"Workspace setup","buyerValue":"Confirm brand, billing, reporting, approval, and constraint context before campaign planning starts.","agentCan":["summarize workspace readiness","identify missing setup fields","prepare onboarding follow-ups"],"humanGate":"Agents cannot create final billing commitments or change organization roles."},{"id":"campaign_intake","label":"Campaign intake","buyerValue":"Turn a product, audience, budget, timing, and claims context into a usable campaign room.","agentCan":["create draft campaign intake","refine brief fields","summarize brand exclusions and claims boundaries"],"humanGate":"Budget changes, final scope, and regulated-claim approval remain human-reviewed."},{"id":"audience_route","label":"Audience route","buyerValue":"Recommend audience pools, example pages, backup supply, creative formats, and route assumptions.","agentCan":["search supply","generate modeled route recommendations","compare requested pages with audience pools"],"humanGate":"Agents cannot book spend, guarantee specific pages, or contact supply owners."},{"id":"creative_production","label":"Creative production","buyerValue":"Translate existing assets into native meme, news, carousel, reel, story, and creator-read packages.","agentCan":["recommend formats","prepare creative work orders","summarize claims/disclosure requirements"],"humanGate":"Final creative approval and placement authorization require named human approval."},{"id":"quote_approval","label":"Quote and approval","buyerValue":"Package route, creative scope, modeled delivery, quote assumptions, caveats, and makegood language.","agentCan":["prepare quote request context","fetch route dossiers","submit recommendation notes to approval gates"],"humanGate":"Agents cannot accept quotes, issue invoices, or authorize spend."},{"id":"placement_proof_reporting","label":"Placement, proof, and reporting","buyerValue":"Track live placements, proof packets, metric source labels, sentiment, organic lift, invoices, and reporting sync.","agentCan":["read proof/report/invoice state","summarize modeled versus verified metrics","flag missing proof or sync issues"],"humanGate":"Publishing reports, validating makegoods, and changing invoice state remain human-controlled."}],"x-cloutops-agent-allowed-actions":["search scoped audience supply","draft campaign intake","update non-consequential brief fields","generate modeled media route recommendations","recommend creative production formats","prepare route/quote context for human review","read scoped reports, invoices, dossiers, packets, and approvals","submit approval recommendations without deciding the gate"],"x-cloutops-metric-trust-rules":["Every estimate should carry a metric source label such as PROFILE_SCRAPED, MODELED_ESTIMATE, OPS_ENTERED, BOOKED, VERIFIED_LIVE, VERIFIED_PERFORMANCE, PINK58_SYNC, or UNAVAILABLE_STALE.","Inventory preview numbers prove supply direction, not guaranteed delivery.","Route numbers are modeled until placements are booked and live performance snapshots are captured.","Pink58 sync is preferred when configured; local snapshots keep dashboards usable when Pink58 is unavailable."],"x-cloutops-primitives":["WorkflowStage","AgentTool","AgentConnectionPacket","ActionCenterItem","CampaignBrief","Campaign","AudiencePool","InventoryPage","MediaRoute","RouteRecommendation","ClientLaunchPlanPacket","FirstFiveOperatingPacket","CampaignLaunchPacket","CreativeProductionPacket","CreativeTemplateLibraryPacket","CreativeProductionRequest","Quote","CreativeVariant","Placement","ApprovalRequest","ReportSnapshot","ReportingProviderStatus","ReportSyncResult","CampaignReport","Invoice","CommercialPacket"],"x-cloutops-metric-sources":["PROFILE_SCRAPED","MODELED_ESTIMATE","OPS_ENTERED","CLIENT_PROVIDED","BOOKED","VERIFIED_LIVE","VERIFIED_PERFORMANCE","INFERRED_ANALYTICS","CLIENT_SITE_VERIFIED","PINK58_SYNC","UNAVAILABLE_STALE"],"x-cloutops-agent-prohibited-actions":["book placements","contact page owners","accept quotes","change budgets","approve final creative","publish reports","issue invoices","override compliance restrictions"],"components":{"securitySchemes":{"AgentBearer":{"type":"http","scheme":"bearer","description":"Agent API token from CLOUTOPS_AGENT_API_KEY."},"AgentApiKey":{"type":"apiKey","in":"header","name":"x-cloutops-agent-key","description":"Alternative header for the same agent API token."}},"schemas":{"MetricSource":{"type":"string","enum":["PROFILE_SCRAPED","MODELED_ESTIMATE","OPS_ENTERED","CLIENT_PROVIDED","BOOKED","VERIFIED_LIVE","VERIFIED_PERFORMANCE","INFERRED_ANALYTICS","CLIENT_SITE_VERIFIED","PINK58_SYNC","UNAVAILABLE_STALE"]},"WorkflowStage":{"type":"object","description":"Agent-readable CloutOps workflow stage. Agents may draft, summarize, compare, and prepare actions in a stage, but human gates remain authoritative.","properties":{"id":{"type":"string"},"label":{"type":"string"},"buyerValue":{"type":"string"},"agentCan":{"type":"array","items":{"type":"string"}},"humanGate":{"type":"string"}}},"AgentTool":{"type":"object","description":"A Claude/ChatGPT-compatible tool description for CloutOps orchestration.","properties":{"name":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PATCH"]},"path":{"type":"string"},"category":{"type":"string"},"workflowStage":{"type":"string"},"description":{"type":"string"},"returns":{"type":"array","items":{"type":"string"}},"approvalRequired":{"type":"boolean"}}},"AgentToolCatalog":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"protocol":{"type":"string"},"description":{"type":"string"},"workflow":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStage"}},"allowedActions":{"type":"array","items":{"type":"string"}},"metricTrustRules":{"type":"array","items":{"type":"string"}},"safety":{"type":"object"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/AgentTool"}}}},"AgentConnectionPacket":{"type":"object","description":"Customer-safe install packet for connecting Claude, ChatGPT, or an internal agent to CloutOps with full URLs, auth expectations, instructions, workflow lanes, and approval firewall rules.","properties":{"name":{"type":"string"},"version":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"purpose":{"type":"string"},"productBoundary":{"type":"object"},"endpoints":{"type":"object"},"auth":{"type":"object"},"setupChecklist":{"type":"array","items":{"type":"object"}},"assistantInstructions":{"type":"string"},"installNotes":{"type":"object"},"toolLanes":{"type":"array","items":{"type":"object"}},"workflow":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStage"}},"tools":{"type":"array","items":{"$ref":"#/components/schemas/AgentTool"}},"allowedActions":{"type":"array","items":{"type":"string"}},"prohibitedActions":{"type":"array","items":{"type":"string"}},"metricTrustRules":{"type":"array","items":{"type":"string"}},"approvalFirewall":{"type":"object"},"testCalls":{"type":"object"}}},"ActionCenterItem":{"type":"object","description":"A buyer-facing or CloutOps-facing next action in a workspace or campaign command center.","properties":{"title":{"type":"string"},"body":{"type":"string"},"href":{"type":"string"},"owner":{"type":"string","enum":["buyer","cloutops","shared","system"]},"priority":{"type":"string","enum":["high","medium","low"]},"status":{"type":"string"},"dueLabel":{"type":"string"},"campaignId":{"type":"string"},"campaignName":{"type":"string"}}},"ReportingProviderStatus":{"type":"object","description":"Runtime reporting adapter status. Agents should explain fallback or derived data plainly to customers.","properties":{"provider":{"type":"string","enum":["local","pink58"]},"configured":{"type":"boolean"},"pink58Url":{"type":"boolean"},"pink58Key":{"type":"boolean"},"label":{"type":"string"},"detail":{"type":"string"}}},"ReportSyncResult":{"type":"object","description":"Result of a report sync attempt. fallback means Pink58 was attempted or expected but local normalized snapshots were used.","properties":{"provider":{"type":"string","enum":["local","pink58"]},"attemptedProvider":{"type":"string","enum":["local","pink58"]},"status":{"type":"string","enum":["synced","fallback","derived"]},"source":{"$ref":"#/components/schemas/MetricSource"},"snapshotId":{"type":"string"},"message":{"type":"string"},"syncedAt":{"type":"string","format":"date-time"}}},"CampaignBrief":{"type":"object","properties":{"id":{"type":"string"},"companyName":{"type":"string"},"objective":{"type":"string"},"audience":{"type":"string"},"budgetRange":{"type":"string"},"timeline":{"type":"string"},"serviceMode":{"type":"string","enum":["FULL_SERVICE","CREATIVE_ONLY","DISTRIBUTION_ONLY","A_LA_CARTE"]},"status":{"type":"string"}}},"Campaign":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["DRAFT","INTAKE_SUBMITTED","QUALIFIED","ROUTE_DRAFTED","QUOTED","APPROVED","ACTIVE","REPORTING","COMPLETE","LOST","PAUSED"]},"goal":{"type":"string"},"budgetRange":{"type":"string"},"timeline":{"type":"string"},"serviceMode":{"type":"string","enum":["FULL_SERVICE","CREATIVE_ONLY","DISTRIBUTION_ONLY","A_LA_CARTE"]}}},"ClientLaunchPlanPacket":{"type":"object","description":"Workspace-level client operating plan for AI assistants: readiness, next owner, buyer actions, risks, meeting agenda, operating rules, and links into campaign packets.","properties":{"id":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"website":{"type":"string"},"industry":{"type":"string"},"regulatoryCategory":{"type":"string"},"reportingNeeds":{"type":"string"}}},"purpose":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"customerValue":{"type":"string"}}},"readiness":{"type":"object","properties":{"workspaceScore":{"type":"integer"},"launchScore":{"type":"integer"},"campaignName":{"type":"string"},"summary":{"type":"string"},"currentStage":{"type":"object"},"readyItems":{"type":"array","items":{"type":"string"}},"risks":{"type":"array","items":{"type":"object"}}}},"primaryAction":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"href":{"type":"string"},"owner":{"type":"string"},"priority":{"type":"string"},"status":{"type":"string"},"dueLabel":{"type":"string"},"campaignName":{"type":"string"}}},"activationSteps":{"type":"array","items":{"type":"object"}},"actionQueue":{"type":"object","properties":{"buyerActions":{"type":"array","items":{"type":"object"}},"cloutOpsWork":{"type":"array","items":{"type":"object"}},"stats":{"type":"array","items":{"type":"object"}}}},"meeting":{"type":"object","properties":{"agenda":{"type":"array","items":{"type":"string"}},"operatingRules":{"type":"array","items":{"type":"string"}},"suggestedOpen":{"type":"string"}}},"currentCampaign":{"type":"object"},"workspaceChecks":{"type":"array","items":{"type":"object"}},"commercialContext":{"type":"object"},"links":{"type":"object"},"guardrails":{"type":"array","items":{"type":"string"}}}},"FirstFiveOperatingPacket":{"type":"object","description":"Workspace-level operating packet for the five systems CloutOps uses to move a brief into delivery: route, creative, supply, campaign room, and finance/proof.","properties":{"id":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string"},"website":{"type":"string","nullable":true},"industry":{"type":"string","nullable":true},"regulatoryCategory":{"type":"string","nullable":true},"reportingNeeds":{"type":"string","nullable":true},"billingEmail":{"type":"string","nullable":true}}},"purpose":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"customerValue":{"type":"string"},"approvalBoundary":{"type":"string"}}},"readiness":{"type":"object","properties":{"score":{"type":"integer"},"workspaceScore":{"type":"integer"},"readyModules":{"type":"integer"},"totalModules":{"type":"integer"},"needsInput":{"type":"integer"},"campaignCount":{"type":"integer"},"summary":{"type":"string"},"updatedLabel":{"type":"string"},"nextAction":{"type":"object"}}},"operatingModel":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["route","creative","supply","room","finance"]},"title":{"type":"string"},"status":{"type":"string","enum":["ready","needs_input","in_progress","waiting"]},"statusLabel":{"type":"string"},"owner":{"type":"string"},"score":{"type":"integer"},"href":{"type":"string"},"customerValue":{"type":"string"},"brandGives":{"type":"string"},"cloutOpsBuilds":{"type":"string"},"approvalArtifact":{"type":"string"},"decisionQuestion":{"type":"string"},"doneWhen":{"type":"string"},"nextAction":{"type":"string"},"missing":{"type":"array","items":{"type":"string"}}}}},"campaigns":{"type":"array","items":{"type":"object"}},"activeCampaign":{"type":"object","nullable":true},"workspace":{"type":"object"},"guardrails":{"type":"array","items":{"type":"string"}},"links":{"type":"object"}}},"CampaignLaunchPacket":{"type":"object","description":"Executive, agent-readable campaign packet combining the delivery operating systems: route approval, creative production, supply/backups, campaign room state, and finance/proof.","properties":{"id":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"campaign":{"$ref":"#/components/schemas/Campaign"},"purpose":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"approvalBoundary":{"type":"string"},"nextMove":{"type":"object"}}},"readiness":{"type":"object","properties":{"firstFiveScore":{"type":"integer"},"workflowScore":{"type":"integer"},"launchReadiness":{"type":"integer"},"blockers":{"type":"array","items":{"type":"string"}}}},"firstFive":{"type":"object"},"routeApproval":{"type":"object"},"creativeProduction":{"type":"object"},"supplyAvailability":{"type":"object"},"brandSuitability":{"type":"object"},"proofReporting":{"type":"object"},"financeProcurement":{"type":"object"},"approvals":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalRequest"}},"links":{"type":"object"}}},"CreativeProductionPacket":{"type":"object","description":"Campaign-level creative production packet for source assets, page-native format systems, claims/disclosure needs, approval state, and route handoff.","properties":{"id":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"campaign":{"$ref":"#/components/schemas/Campaign"},"purpose":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"buyerDecision":{"type":"string"},"approvalBoundary":{"type":"string"}}},"readiness":{"type":"object","properties":{"score":{"type":"integer"},"lane":{"type":"string"},"nextAction":{"type":"string"},"missingInputs":{"type":"array","items":{"type":"string"}},"creativeCount":{"type":"integer"},"approvedCount":{"type":"integer"},"inReviewCount":{"type":"integer"},"pendingApprovalCount":{"type":"integer"}}},"productionOrder":{"type":"object","description":"Buyer-readable creative work order: scope, deliverables, approval boundary, brand next steps, CloutOps next steps, and route handoff requirements.","properties":{"scope":{"type":"object","properties":{"mode":{"type":"string"},"label":{"type":"string"},"buyerPromise":{"type":"string"},"included":{"type":"array","items":{"type":"string"}},"notIncluded":{"type":"array","items":{"type":"string"}}}},"buyerDecision":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"approveWhen":{"type":"array","items":{"type":"string"}},"doNotApproveUntil":{"type":"array","items":{"type":"string"}}}},"orderQueue":{"type":"object","properties":{"brandNext":{"type":"array","items":{"type":"string"}},"cloutOpsNext":{"type":"array","items":{"type":"string"}},"legalFinanceNext":{"type":"array","items":{"type":"string"}}}},"deliverables":{"type":"array","items":{"type":"object"}},"productionRules":{"type":"array","items":{"type":"string"}},"routeHandoff":{"type":"object"}}},"intake":{"type":"object","properties":{"desiredFormats":{"type":"array","items":{"type":"string"}},"claimBoundaries":{"type":"string"},"requiredDisclaimers":{"type":"string"},"brandConstraints":{"type":"string"},"forbiddenTopics":{"type":"array","items":{"type":"string"}},"existingTopAds":{"type":"array","items":{"type":"string"}}}},"sourcePacket":{"type":"object","properties":{"totalAssets":{"type":"integer"},"rightsReady":{"type":"integer"},"remixable":{"type":"integer"},"referenceLinks":{"type":"array","items":{"type":"object"}},"assets":{"type":"array","items":{"type":"object"}}}},"formatSystem":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"promise":{"type":"string"},"status":{"type":"string"},"statusDetail":{"type":"string"},"requiredInputs":{"type":"array","items":{"type":"object"}},"approvalPacket":{"type":"array","items":{"type":"string"}},"routeHandoff":{"type":"array","items":{"type":"string"}}}}},"creativePackages":{"type":"array","items":{"$ref":"#/components/schemas/CreativeVariant"}},"routeHandoff":{"type":"object"},"approvals":{"type":"object"},"guardrails":{"type":"array","items":{"type":"string"}},"links":{"type":"object"}}},"CreativeTemplateLibraryPacket":{"type":"object","description":"Reusable creative template library for meme, news, text-over-video, and mixed-carousel creative production.","properties":{"id":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"purpose":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"customerValue":{"type":"string"}}},"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["meme","news","video","mixed-carousel"]},"name":{"type":"string"},"output":{"type":"string"},"purpose":{"type":"string"},"buyerPromise":{"type":"string"},"bestFor":{"type":"array","items":{"type":"string"}},"requiredInputs":{"type":"array","items":{"type":"object"}},"productionFields":{"type":"array","items":{"type":"object"}},"briefFields":{"type":"array","items":{"type":"string"}},"approvalChecks":{"type":"array","items":{"type":"string"}},"handoffPackage":{"type":"array","items":{"type":"string"}},"routeHandoff":{"type":"array","items":{"type":"string"}},"pageFit":{"type":"array","items":{"type":"string"}},"visualRules":{"type":"array","items":{"type":"string"}},"developmentStages":{"type":"array","items":{"type":"string"}},"archetypes":{"type":"array","items":{"type":"object"}},"references":{"type":"array","items":{"type":"object"}}}}},"intakeRules":{"type":"array","items":{"type":"string"}},"approvalRules":{"type":"array","items":{"type":"string"}},"agentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"links":{"type":"object"}}},"AudiencePool":{"type":"object","properties":{"niche":{"type":"string"},"pageCount":{"type":"integer"},"estimatedReach":{"type":"integer"},"examplePages":{"type":"array","items":{"type":"string"}},"metricSources":{"type":"array","items":{"$ref":"#/components/schemas/MetricSource"}}}},"InventoryPage":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"platform":{"type":"string"},"displayName":{"type":"string"},"followerCount":{"type":"integer"},"averageViews":{"type":"integer"},"engagementRate":{"type":"number"},"primaryNiche":{"type":"string"},"audienceDemo":{"type":"array","items":{"type":"string"}},"contentFormat":{"type":"array","items":{"type":"string"}},"metricSources":{"type":"array","items":{"$ref":"#/components/schemas/MetricSource"}}}},"MediaRoute":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"version":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string"},"estimatedReach":{"type":"integer"},"estimatedViews":{"type":"integer"},"cpmRange":{"type":"string"},"audiencePools":{"type":"array","items":{"type":"string"}},"availabilityCaveat":{"type":"string"},"metricSources":{"type":"array","items":{"$ref":"#/components/schemas/MetricSource"}}}},"RouteRecommendation":{"type":"object","properties":{"route":{"$ref":"#/components/schemas/MediaRoute"},"primaryPages":{"type":"array","items":{"$ref":"#/components/schemas/InventoryPage"}},"backupPages":{"type":"array","items":{"$ref":"#/components/schemas/InventoryPage"}},"assumptions":{"type":"array","items":{"type":"string"}},"approvalRequired":{"type":"boolean"}}},"Quote":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"routeId":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["DRAFT","SENT","APPROVED","REJECTED","EXPIRED","SUPERSEDED"]},"totalAmountCents":{"type":"integer"},"budgetRange":{"type":"string"},"estimatedDelivery":{"type":"string"},"cpmRange":{"type":"string"},"assumptions":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLineItem"}}}},"QuoteLineItem":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["STRATEGY","CREATIVE_PRODUCTION","DISTRIBUTION","REPORTING","RUSH_PREMIUM","USAGE_RIGHTS","MANAGED_SERVICE_FEE","OTHER"]},"description":{"type":"string"},"amountCents":{"type":"integer"}}},"CreativeVariant":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"format":{"type":"string"},"concept":{"type":"string"},"hook":{"type":"string"},"cta":{"type":"string"},"targetAudience":{"type":"string"},"status":{"type":"string","enum":["DRAFT","INTERNAL_REVIEW","CLIENT_REVIEW","IN_REVIEW","APPROVED","CHANGES_REQUESTED","REJECTED","APPROVED_FOR_PLACEMENT","LIVE","ARCHIVED"]},"claimsChecklist":{"type":"object"},"performanceTags":{"type":"array","items":{"type":"string"}}}},"Placement":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"routeId":{"type":"string"},"routePageId":{"type":"string"},"pageHandle":{"type":"string"},"creativeVariantId":{"type":"string"},"status":{"type":"string","enum":["PROPOSED","AVAILABILITY_PENDING","QUOTED","APPROVED","RESERVED","SCHEDULED","LIVE","PROOFED","COMPLETE","ISSUE"]},"scheduledAt":{"type":"string","format":"date-time"},"liveAt":{"type":"string","format":"date-time"},"liveUrl":{"type":"string"},"metricSources":{"type":"array","items":{"$ref":"#/components/schemas/MetricSource"}}}},"ApprovalRequest":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"subjectType":{"type":"string","enum":["CAMPAIGN","ROUTE","QUOTE","CREATIVE","PLACEMENT","REPORT","INVOICE"]},"subjectId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CHANGES_REQUESTED"]},"title":{"type":"string"},"summary":{"type":"string"}}},"ReportSnapshot":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"source":{"$ref":"#/components/schemas/MetricSource"},"reach":{"type":"integer"},"views":{"type":"integer"},"engagement":{"type":"integer"},"clicks":{"type":"integer"},"spendCents":{"type":"integer"},"sentiment":{"type":"object"},"organicLift":{"type":"object"},"metricSources":{"type":"object"}}},"CampaignReportSummary":{"type":"object","description":"Normalized summary metrics for a campaign with source, provider, and sync provenance.","properties":{"reach":{"type":"integer"},"views":{"type":"integer"},"engagement":{"type":"integer"},"clicks":{"type":"integer","nullable":true},"spendCents":{"type":"integer","nullable":true},"cpm":{"type":"number","nullable":true},"source":{"$ref":"#/components/schemas/MetricSource"},"sourceLabels":{"type":"object","additionalProperties":{"type":"string"}},"provider":{"type":"string","enum":["local","pink58","derived"]},"attemptedProvider":{"type":"string","enum":["local","pink58"]},"syncStatus":{"type":"string","enum":["synced","fallback","derived"]},"syncMessage":{"type":"string"},"syncedAt":{"type":"string","format":"date-time","nullable":true}}},"PlacementMetric":{"type":"object","properties":{"handle":{"type":"string"},"platform":{"type":"string"},"views":{"type":"integer"},"engagement":{"type":"integer"},"liveUrl":{"type":"string","nullable":true},"source":{"$ref":"#/components/schemas/MetricSource"},"windowLabel":{"type":"string","nullable":true}}},"CreativeMetric":{"type":"object","properties":{"creativeId":{"type":"string"},"format":{"type":"string"},"views":{"type":"integer"},"engagement":{"type":"integer"},"source":{"$ref":"#/components/schemas/MetricSource"}}},"SentimentReport":{"type":"object","properties":{"positive":{"type":"number"},"neutral":{"type":"number"},"negative":{"type":"number"},"themes":{"type":"array","items":{"type":"string"}},"notableComments":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"}}},"CampaignReport":{"type":"object","description":"Agent-readable campaign report. Agents should preserve source labels and sync status when summarizing performance.","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"summary":{"$ref":"#/components/schemas/CampaignReportSummary"},"placements":{"type":"array","items":{"$ref":"#/components/schemas/PlacementMetric"}},"creatives":{"type":"array","items":{"$ref":"#/components/schemas/CreativeMetric"}},"sentiment":{"$ref":"#/components/schemas/SentimentReport"},"organicLift":{"type":"object"},"providerStatus":{"$ref":"#/components/schemas/ReportingProviderStatus"},"snapshotHistory":{"type":"array","items":{"$ref":"#/components/schemas/ReportSnapshot"}},"guardrails":{"type":"object","properties":{"readOnly":{"type":"boolean"},"modeledValuesAreNotVerifiedPerformance":{"type":"boolean"},"reportPublicationRequiresHumanApproval":{"type":"boolean"}}},"provenance":{"type":"object"}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"quoteId":{"type":"string"},"invoiceNumber":{"type":"string"},"status":{"type":"string","enum":["DRAFT","SENT","VIEWED","PARTIALLY_PAID","PAID","VOID","OVERDUE"]},"amountCents":{"type":"integer"},"dueDate":{"type":"string","format":"date-time"},"proofPacketUrl":{"type":"string"},"paymentTerms":{"type":"string"},"makegoodMemo":{"type":"string"}}}}},"paths":{"/api/agent/tools":{"get":{"operationId":"getAgentTools","summary":"Get the CloutOps agent tool catalog","responses":{"200":{"description":"Tool catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentToolCatalog"}}}}}}},"/api/agent/connection-kit":{"get":{"operationId":"getAgentConnectionKit","summary":"Get the customer install packet for assistant connections","description":"Returns full endpoint URLs, auth/header expectations, setup checklist, copy/paste assistant instructions, ChatGPT/Claude/internal-agent install notes, workflow lanes, and approval firewall rules. This endpoint is discovery-safe and does not expose secrets.","responses":{"200":{"description":"Agent connection packet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConnectionPacket"}}}}}}},"/api/agent/launch-plan":{"get":{"operationId":"getClientLaunchPlan","summary":"Get client launch plan","description":"Returns the workspace-level client launch plan for AI assistants: readiness, next owner, buyer actions, CloutOps work, risks, ready evidence, meeting agenda, operating rules, packet links, and approval-safe guardrails. It is read-only and cannot approve, book, publish, or issue anything.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md","markdown"]},"description":"Use md or markdown for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Client launch plan packet","content":{"application/json":{"schema":{"type":"object","properties":{"packet":{"$ref":"#/components/schemas/ClientLaunchPlanPacket"},"guardrails":{"type":"object"},"recommendedAgentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"503":{"description":"Agent API is not configured"}}}},"/api/agent/first-five":{"get":{"operationId":"getFirstFiveOperatingPacket","summary":"Get delivery operating packet","description":"Returns the workspace-level delivery operating packet for AI assistants: route dossier readiness, creative production readiness, supply availability readiness, campaign room readiness, finance/proof readiness, missing checks, buyer inputs, CloutOps outputs, approval artifacts, guardrails, and campaign links. It is read-only and cannot approve, book, publish, or issue anything.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md","markdown"]},"description":"Use md or markdown for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Delivery operating packet","content":{"application/json":{"schema":{"type":"object","properties":{"packet":{"$ref":"#/components/schemas/FirstFiveOperatingPacket"},"guardrails":{"type":"object"},"recommendedAgentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"503":{"description":"Agent API is not configured"}}}},"/api/agent/plan":{"post":{"operationId":"generateMediaPlan","summary":"Generate a draft media route","description":"Returns audience pools, example pages, creative units, commercial estimate, source labels, managed-plan risk notes, reporting plan, and approval gates. It does not book spend.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["objective","audience"],"properties":{"companyName":{"type":"string"},"objective":{"type":"string","example":"Drive awareness for a dating app launch"},"audience":{"type":"string","example":"Young men interested in dating humor and relationship content"},"budgetRange":{"type":"string","example":"$50k"},"timeline":{"type":"string","example":"Launch in the next 30 days"},"campaignGoal":{"type":"string","example":"awareness"},"desiredFormats":{"type":"array","items":{"type":"string"},"example":["meme-native post","reels repost package"]},"preferredNiches":{"type":"array","items":{"type":"string"},"example":["Dating / Romance","Meme / Humor"]},"specificPages":{"type":"array","items":{"type":"string"},"example":["@pickuplines"]},"excludedBrandSafety":{"type":"array","items":{"type":"string","enum":["SAFE","CAUTION","RESTRICTED","UNSAFE","UNREVIEWED"]},"example":["UNSAFE","RESTRICTED"]},"claimBoundaries":{"type":"string"},"requiredDisclaimers":{"type":"string"},"forbiddenTopics":{"type":"array","items":{"type":"string"}},"existingTopAds":{"type":"array","items":{"type":"string"}},"regulatedCategory":{"type":"string"},"brandExclusions":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Draft media plan"},"400":{"description":"Invalid request"}}}},"/api/inventory":{"get":{"operationId":"searchAudienceSupply","summary":"Search available audience supply","description":"Returns public supply examples for route planning. This is not a full marketplace feed and does not expose internal failures, owner/contact notes, pricing history, or availability holds.","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"niche","in":"query","schema":{"type":"string"}},{"name":"intent","in":"query","schema":{"type":"string"}},{"name":"goal","in":"query","schema":{"type":"string"}},{"name":"demo","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching inventory pages"}}}},"/api/agent/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns for the org-scoped agent workspace","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"responses":{"200":{"description":"Campaigns"},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"}}},"post":{"operationId":"createCampaign","summary":"Create a campaign intake and draft route through an org-scoped agent token","description":"Requires agent:write. Creates draft workflow records only; spend, final pricing, placements, reports, and invoices remain approval-gated.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","objective","audience","product"],"properties":{"name":{"type":"string"},"objective":{"type":"string"},"audience":{"type":"string"},"product":{"type":"string"},"offer":{"type":"string"},"landingPageUrl":{"type":"string"},"budgetRange":{"type":"string"},"timeline":{"type":"string"},"campaignGoal":{"type":"string"},"serviceMode":{"type":"string","enum":["FULL_SERVICE","CREATIVE_ONLY","DISTRIBUTION_ONLY","A_LA_CARTE"]},"requestedPages":{"type":"array","items":{"type":"string"}},"avoidedPages":{"type":"array","items":{"type":"string"}},"desiredFormats":{"type":"array","items":{"type":"string"}},"brandConstraints":{"type":"string"},"claimBoundaries":{"type":"string"},"requiredDisclaimers":{"type":"string"},"forbiddenTopics":{"type":"array","items":{"type":"string"}},"existingTopAds":{"type":"array","items":{"type":"string"}},"approvalContacts":{"type":"array","items":{"type":"string"}},"regulatedCategory":{"type":"string"},"brandExclusions":{"type":"array","items":{"type":"string"}},"reportingNeeds":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Created campaign"},"400":{"description":"Invalid campaign"},"401":{"description":"Unauthorized"},"403":{"description":"Missing agent write scope or organization scope"}}}},"/api/agent/campaigns/{campaignId}":{"get":{"operationId":"getCampaign","summary":"Get campaign route, creative, placements, invoices, and approvals through an org-scoped agent token","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign"},"404":{"description":"Campaign not found"}}},"patch":{"operationId":"updateCampaignIntake","summary":"Update non-consequential campaign intake","description":"Requires agent:write. Does not directly change budget or book spend; proposed budget changes create approval requests.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated campaign"},"400":{"description":"Invalid update"},"404":{"description":"Campaign not found"}}}},"/api/agent/campaigns/{campaignId}/report":{"get":{"operationId":"getCampaignReport","summary":"Get normalized campaign report","description":"Returns a read-only normalized report with provider status, source labels, sync state, placement and creative metrics, sentiment, organic lift, and snapshot history. Modeled values must not be presented as verified performance.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignReport"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"404":{"description":"Campaign not found"}}}},"/api/agent/campaigns/{campaignId}/route-dossier":{"get":{"operationId":"getRouteDossier","summary":"Get route approval dossier","description":"Returns the client-facing route approval packet: audience rationale, target pages, backups, source labels, modeled-vs-verified caveats, disclosure plan, quote assumptions, makegood terms, readiness checks, and approval gates.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]},"description":"Use md for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Route dossier packet"},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"404":{"description":"Campaign not found"}}}},"/api/agent/campaigns/{campaignId}/launch-packet":{"get":{"operationId":"getCampaignLaunchPacket","summary":"Get campaign launch packet","description":"Returns the executive launch packet that combines route approval, creative production, supply/backups, campaign room state, proof/reporting, finance/procurement, approvals, source labels, and agent-safe next actions. It is read-only and does not approve, book, publish, or issue anything.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","md","markdown"]},"description":"Use md or markdown for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Campaign launch packet","content":{"application/json":{"schema":{"type":"object","properties":{"packet":{"$ref":"#/components/schemas/CampaignLaunchPacket"},"guardrails":{"type":"object"},"recommendedAgentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"404":{"description":"Campaign not found"}}}},"/api/agent/campaigns/{campaignId}/creative-packet":{"get":{"operationId":"getCreativeProductionPacket","summary":"Get creative production packet","description":"Returns the campaign-level creative production packet: source assets, references, format systems, claims/disclosure needs, creative package readiness, export state, approval gates, route handoff, and agent-safe guardrails. It is read-only and does not approve final creative or spend.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","md","markdown"]},"description":"Use md or markdown for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Creative production packet","content":{"application/json":{"schema":{"type":"object","properties":{"packet":{"$ref":"#/components/schemas/CreativeProductionPacket"},"guardrails":{"type":"object"},"recommendedAgentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"404":{"description":"Campaign not found"}}}},"/api/agent/creative-templates":{"get":{"operationId":"getCreativeTemplateLibrary","summary":"Get creative template library","description":"Returns the reusable CloutOps creative template library: meme, news, text-over-video, and mixed-carousel templates with required inputs, production fields, approval checks, route handoff requirements, brief fields, archetypes, and agent-safe guardrails. It is read-only and does not approve final creative or spend.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md","markdown"]},"description":"Use md or markdown for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Creative template library packet","content":{"application/json":{"schema":{"type":"object","properties":{"packet":{"$ref":"#/components/schemas/CreativeTemplateLibraryPacket"},"guardrails":{"type":"object"},"recommendedAgentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"503":{"description":"Agent API is not configured"}}}},"/api/agent/campaigns/{campaignId}/creative-requests":{"post":{"operationId":"requestCreativeProduction","summary":"Request draft creative production","description":"Requires agent:write. Creates a draft native creative package, export spec, ops production task, and audit record. It does not approve final creative, clear rights or claims, authorize placement, or book spend.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requestTitle","desiredHook"],"properties":{"formatKey":{"type":"string","enum":["meme","news","video","mixed-carousel"],"default":"meme","description":"Native package type to draft."},"requestTitle":{"type":"string","example":"Dating app white-background meme opener"},"desiredHook":{"type":"string","example":"when the group chat finally gets your dating life"},"priority":{"type":"string","enum":["LOW","MEDIUM","HIGH","URGENT"],"default":"MEDIUM"},"product":{"type":"string"},"offer":{"type":"string"},"audience":{"type":"string"},"sourceMaterial":{"type":"string","description":"Files, screenshots, product shots, clips, comments, proof, or scene notes."},"referenceUrls":{"type":"array","items":{"type":"string"},"example":["https://www.instagram.com/p/example/"]},"assetId":{"type":"string","description":"Optional existing campaign asset to attach."},"rightsNotes":{"type":"string"},"audienceTension":{"type":"string"},"productTruth":{"type":"string"},"proofPoint":{"type":"string"},"brandBridge":{"type":"string"},"cta":{"type":"string"},"routeFit":{"type":"string"},"captionPrompt":{"type":"string"},"archetypeName":{"type":"string"},"backgroundTreatment":{"type":"string","description":"For reel packages: black, white, or page-matched treatment."},"editNotes":{"type":"string"},"slideOneFormat":{"type":"string"},"memeFollowUp":{"type":"string"},"claimBoundaries":{"type":"string"},"requiredDisclaimers":{"type":"string"},"prohibitedTopics":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Draft creative package created; human approval still required","content":{"application/json":{"schema":{"type":"object","properties":{"creative":{"$ref":"#/components/schemas/CreativeVariant"},"packet":{"type":"object"},"guardrails":{"type":"object"},"recommendedNextActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}}}},"400":{"description":"Invalid creative production request"},"401":{"description":"Unauthorized"},"403":{"description":"Missing agent write scope, organization scope, or creative permission"},"404":{"description":"Campaign or asset not found"}}}},"/api/agent/invoices/{invoiceId}":{"get":{"operationId":"getInvoiceStatus","summary":"Get invoice commercial packet","description":"Returns the read-only commercial packet for an invoice: quote/IO scope, line items, PO and signed-document context, manual payment state, proof evidence, source labels, makegoods, and procurement readiness. It does not issue invoices, accept quotes, record payments, or book placements.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","md","markdown"]},"description":"Use md or markdown for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Invoice commercial packet","content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/Invoice"},"packet":{"type":"object"},"balance":{"type":"object"},"guardrails":{"type":"object"},"recommendedAgentUse":{"type":"array","items":{"type":"string"}},"prohibitedAgentActions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object"}}}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"404":{"description":"Invoice not found"}}}},"/api/agent/approvals/{approvalId}":{"post":{"operationId":"submitApproval","summary":"Submit an agent approval recommendation","description":"Requires agent:write. Records an agent recommendation and audit entry only. It does not decide the approval gate or mutate route, quote, creative, placement, report, or invoice state.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"approvalId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","decisionNotes"],"properties":{"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CHANGES_REQUESTED"]},"decisionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Approval recommendation recorded; human decision still required"},"400":{"description":"Invalid recommendation"},"401":{"description":"Unauthorized"},"403":{"description":"Missing agent write scope or organization scope"},"404":{"description":"Approval not found"}}}},"/api/agent/approvals/{approvalId}/packet":{"get":{"operationId":"getApprovalPacket","summary":"Get approval packet","description":"Returns the exportable approval packet with subject summary, named approvers, timing, guardrails, decision notes, and audit trail.","security":[{"AgentBearer":[]},{"AgentApiKey":[]}],"parameters":[{"name":"approvalId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]},"description":"Use md for Markdown. Omit or use json for JSON."},{"name":"download","in":"query","schema":{"type":"string","enum":["json","1"]},"description":"Request an attachment response."}],"responses":{"200":{"description":"Approval packet"},"401":{"description":"Unauthorized"},"403":{"description":"Agent organization scope missing"},"404":{"description":"Approval not found"}}}},"/api/briefs":{"post":{"operationId":"createCampaignBrief","summary":"Create a campaign brief for ops review","responses":{"201":{"description":"Created campaign brief"},"400":{"description":"Invalid brief"}}}},"/api/placements/request":{"post":{"operationId":"requestPagePlacement","summary":"Request placement review for a specific page","description":"Approval-gated. Ops must confirm availability and final pricing.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["pageId"],"properties":{"pageId":{"type":"string"}}}}}},"responses":{"200":{"description":"Placement request created"},"404":{"description":"Page not found"}}}}}}