{"openapi":"3.1.0","info":{"title":"Sportsmarks Licensing API","version":"2.0.0","description":"Tenant-scoped licensing API for brands and institutions. Authenticate with an `sm_live_…` bearer key; the key carries the principal (brand or institution) and its scopes, so no tenant id appears in any path. Successful responses are wrapped in `{ \"data\": … }`."},"servers":[{"url":"https://sportsmarks.com/api"}],"security":[{"apiKey":[]}],"tags":[{"name":"core","description":"Identity, events and the spec itself"},{"name":"brand","description":"Endpoints for brand (licensee) keys"},{"name":"institution","description":"Endpoints for institution (licensor) keys"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An `sm_live_…` API key issued from a brand or licensor workspace."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"]}}},"paths":{"/v2/brand":{"get":{"operationId":"getBrand","summary":"The brand behind the key, with its derived facts","description":"The brand record plus the current fact snapshot (revenue, channels, categories, documents on file) that requirements are evaluated against.\n\nRequired scope: `profile:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":["string","null"]},"legal_name":{"type":["string","null"]},"website_domain":{"type":["string","null"]},"description":{"type":["string","null"]},"facts":{"type":"object","additionalProperties":{}}},"required":["id","name","slug","status","legal_name","website_domain","description","facts"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/application":{"get":{"operationId":"getBrandApplication","summary":"Read the brand's licensing application","description":"The single platform-level application shared across every institution the brand applies to. Created as an empty draft on first read.\n\nRequired scope: `applications:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"put":{"operationId":"putBrandApplication","summary":"Replace the brand's application payload","description":"Writes the whole application payload (it is not a patch). Saving recomputes completeness and refreshes the fact snapshot, so readiness reflects the new answers immediately.\n\nRequired scope: `applications:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}},"/v2/brand/applications":{"get":{"operationId":"getBrandApplications","summary":"List the brand's submissions","description":"Every submission the brand has made, with status, decision, readiness at submit time and the latest screening outcome.\n\nRequired scope: `applications:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postBrandApplications","summary":"Submit to one or more institutions","description":"Freezes the current application and profile snapshot and opens a submission per institution. Institutions that already have an open submission, or are not accepting applications, come back under `skipped` instead of failing the call.\n\nRequired scope: `applications:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"submission_id":{"type":"string","format":"uuid"},"institution_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["submission_id","institution_id","status"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"institution_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"status":{"type":"string"}},"required":["institution_id","reason"]}}},"required":["created","skipped"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"institution_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50}},"required":["institution_ids"]}}}}}},"/v2/brand/applications/{submissionId}":{"get":{"operationId":"getBrandApplicationsBySubmissionId","summary":"One submission, brand view","description":"Full submission detail including status history and a screening summary. AI reasoning is stripped: brands see outcomes, not the licensor's internal notes.\n\nRequired scope: `applications:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postBrandApplicationsBySubmissionId","summary":"Withdraw or resubmit","description":"`withdraw` closes an open submission. `resubmit` re-opens one that was denied or that asked for more information, re-freezing the current profile.\n\nRequired scope: `applications:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["withdraw","resubmit"]}},"required":["action"]}}}}}},"/v2/brand/connections":{"get":{"operationId":"getBrandConnections","summary":"List sales-channel connections","description":"Connected commerce platforms (Shopify today) with status, scopes and last sync. Secrets are never returned.\n\nRequired scope: `profile:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postBrandConnections","summary":"Start a connection","description":"In `oauth` mode returns `{ url }` for the provider's consent screen (requires a session-backed principal, because the handshake is tied to a user). In `manual_token` mode saves a pasted token and returns the connection.\n\nRequired scope: `connections:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"connections:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"state":{"type":"string"},"connection":{"type":"object","additionalProperties":{}}}}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["shopify"]},"mode":{"type":"string","enum":["oauth","manual_token"],"default":"oauth"},"input":{"type":"object","additionalProperties":{"type":"string"},"default":{}}},"required":["provider"]}}}}}},"/v2/brand/discovery":{"get":{"operationId":"getBrandDiscovery","summary":"Latest discovery run","description":"The most recent discovery run for the brand, or null.\n\nRequired scope: `profile:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"brand_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","error"]},"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"state":{"type":"string"},"count":{"type":"number"}},"required":["key","label","state"]}},"summary":{"type":["object","null"],"additionalProperties":{}},"error_message":{"type":["string","null"]},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","brand_id","domain","status","steps","summary","error_message","started_at","completed_at","created_at"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postBrandDiscovery","summary":"Read the brand's public website and socials","description":"Step 1 of applying. Starts an asynchronous discovery run over the brand's site (platform, products, prices, categories, channels, regions) and public social pages, then builds the profile snapshot. Everything it finds is public, unverified evidence: enough for a soft approval, never a hard one. Poll the run until `status` is `complete`.\n\nRequired scope: `profile:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"brand_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","error"]},"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"state":{"type":"string"},"count":{"type":"number"}},"required":["key","label","state"]}},"summary":{"type":["object","null"],"additionalProperties":{}},"error_message":{"type":["string","null"]},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","brand_id","domain","status","steps","summary","error_message","started_at","completed_at","created_at"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253},"socials":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","facebook","x","youtube","linkedin","pinterest"]},"handle":{"type":"string","minLength":1,"maxLength":80}},"required":["platform","handle"]},"maxItems":8}},"required":["domain"]}}}}}},"/v2/brand/discovery/{runId}":{"get":{"operationId":"getBrandDiscoveryByRunId","summary":"Discovery run progress","description":"Ordered steps with state and counts while running; the summary (platform, products, categories, channels, socials, warnings) once complete.\n\nRequired scope: `profile:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"brand_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","error"]},"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"state":{"type":"string"},"count":{"type":"number"}},"required":["key","label","state"]}},"summary":{"type":["object","null"],"additionalProperties":{}},"error_message":{"type":["string","null"]},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","brand_id","domain","status","steps","summary","error_message","started_at","completed_at","created_at"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/documents":{"get":{"operationId":"getBrandDocuments","summary":"List uploaded compliance documents","description":"Documents on file (COI, W-9, FLA and friends) with extraction status and the data pulled out of them.\n\nRequired scope: `profile:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/grants":{"get":{"operationId":"getBrandGrants","summary":"List the brand's licence grants","description":"Every grant issued to the brand, with the institution, status and the number of approved rights lines.\n\nRequired scope: `grants:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"grants:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/grants/{grantId}":{"get":{"operationId":"getBrandGrantsByGrantId","summary":"One grant in full","description":"The grant with its rights lines (channel, category, logo or group, territory) and the active royalty rate schedule.\n\nRequired scope: `grants:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"grants:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postBrandGrantsByGrantId","summary":"Sign a grant as the brand","description":"Countersigns a grant that the institution has sent for signature. Signing is the only grant action available to a brand key; every other transition belongs to the licensor.\n\nRequired scope: `grants:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"grants:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","const":"sign"}},"required":["action"]}}}}}},"/v2/brand/institutions":{"get":{"operationId":"getBrandInstitutions","summary":"Institutions the brand can apply to","description":"Each institution with its requirement counts (total and hard gates), whether it is accepting applications, the brand's open submission if there is one, and the cached readiness score.\n\nRequired scope: `applications:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"accepting_applications":{"type":"boolean"},"review_sla_days":{"type":["number","null"]},"requirements":{"type":"object","properties":{"total":{"type":"integer"},"hard":{"type":"integer"}},"required":["total","hard"]},"submission":{"type":["object","null"],"additionalProperties":{}},"readiness":{"type":["object","null"],"additionalProperties":{}}},"required":["id","name","slug","accepting_applications","review_sla_days","requirements","submission","readiness"]}}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":80}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}]}},"/v2/brand/institutions/{institutionId}/readiness":{"get":{"operationId":"getBrandInstitutionsByInstitutionIdReadiness","summary":"Readiness against one institution","description":"Recomputes the deterministic readiness check now: a score, an eligibility flag, and a per-requirement predicted result with the evidence behind it. Use it before submitting to see exactly what is missing.\n\nRequired scope: `applications:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"score":{"type":"number"},"eligible":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["score","eligible","results"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institutionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/logos":{"get":{"operationId":"getBrandLogos","summary":"Logos the brand is licensed to use right now","description":"Grouped by grant: every logo covered by an approved line of an active grant, with public file URLs. This is the endpoint to call before putting a mark on a product.\n\nRequired scope: `logos:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"logos:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/recommendations":{"get":{"operationId":"getBrandRecommendations","summary":"Institutions likely to approve this brand","description":"Step 3 of applying. Every institution accepting applications, tiered `likely` / `possible` / `unlikely` by the same deterministic rules screening uses, with category fit, the institution's automatic-decision modes, any open submission, and the top reasons behind gaps. Reasons marked `unverified` are fixable by connecting a store.\n\nRequired scope: `applications:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"applications:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"institution_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":["string","null"]},"tier":{"type":"string","enum":["likely","possible","unlikely"]},"score":{"type":"number"},"eligible":{"type":"boolean"},"unknown_hard":{"type":"integer"},"failed_hard":{"type":"integer"},"unverified_hard":{"type":"integer"},"category_fit":{"type":"integer"},"auto_approve_mode":{"type":"string","enum":["manual","soft","hard"]},"auto_deny_mode":{"type":"string","enum":["manual","soft","hard"]},"review_sla_days":{"type":["integer","null"]},"submission":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["id","status"]},"top_reasons":{"type":"array","items":{"type":"object","properties":{"requirement_type_code":{"type":"string"},"predicted":{"type":"string"},"verification":{"type":"string"},"label":{"type":"string"}},"required":["requirement_type_code","predicted","verification","label"]}}},"required":["institution_id","name","slug","tier","score","eligible","unknown_hard","failed_hard","unverified_hard","category_fit","auto_approve_mode","auto_deny_mode","review_sla_days","submission","top_reasons"]}}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/brand/revenue":{"get":{"operationId":"getBrandRevenue","summary":"Royalty-bearing revenue summary","description":"Net sales in the window grouped by institution, channel or category, plus the unattributed remainder (sales no institution is being paid on). Defaults to the trailing twelve months.\n\nRequired scope: `revenue:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"revenue:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string"}}]}},"/v2/brand/sales-channels":{"get":{"operationId":"getBrandSalesChannels","summary":"Where the brand sells","description":"Storefront and retailer links (Amazon, Etsy, Walmart, eBay, Faire, wholesale retailers, the website) with the channel class each implies and what discovery read at the link. Self-reported or discovered on the brand's site.\n\nRequired scope: `profile:read`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:read","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"brand_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["website","shopify","amazon","etsy","walmart","ebay","faire","wholesale_retailer","other"]},"channel_class":{"type":"string","enum":["direct","wholesale","marketplace"]},"url":{"type":"string"},"label":{"type":["string","null"]},"source":{"type":"string","enum":["self_reported","discovered"]},"last_read_at":{"type":["string","null"]},"read_summary":{"type":["object","null"],"additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","brand_id","kind","channel_class","url","label","source","last_read_at","read_summary","created_at"]}}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postBrandSalesChannels","summary":"Add a sales channel link","description":"Adds a storefront or retailer link. The kind is detected from the host when omitted; wholesale retailers should pass kind and a label. Adding a link re-derives the profile and re-screens open applications.\n\nRequired scope: `profile:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"brand_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["website","shopify","amazon","etsy","walmart","ebay","faire","wholesale_retailer","other"]},"channel_class":{"type":"string","enum":["direct","wholesale","marketplace"]},"url":{"type":"string"},"label":{"type":["string","null"]},"source":{"type":"string","enum":["self_reported","discovered"]},"last_read_at":{"type":["string","null"]},"read_summary":{"type":["object","null"],"additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","brand_id","kind","channel_class","url","label","source","last_read_at","read_summary","created_at"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":3,"maxLength":500},"kind":{"type":"string","enum":["website","shopify","amazon","etsy","walmart","ebay","faire","wholesale_retailer","other"]},"label":{"type":["string","null"],"maxLength":120}},"required":["url"]}}}}}},"/v2/brand/sales-channels/{channelId}":{"delete":{"operationId":"deleteBrandSalesChannelsByChannelId","summary":"Remove a sales channel link","description":"Removes a link and re-derives the profile.\n\nRequired scope: `profile:write`.","tags":["brand"],"security":[{"apiKey":[]}],"x-scope":"profile:write","x-principal":"brand","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/events":{"get":{"operationId":"getEvents","summary":"Page the tenant's event log","description":"Events for the caller's tenant in `id` order. Poll with `since` set to the last id you processed; `next_cursor` is the id to pass next time (null when you have caught up).\n\nRequired scope: `events:read`.","tags":["core"],"security":[{"apiKey":[]}],"x-scope":"events:read","x-principal":"any","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"event_uuid":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"occurred_at":{"type":"string"},"brand_id":{"type":["string","null"],"format":"uuid"},"institution_id":{"type":["string","null"],"format":"uuid"},"entity_type":{"type":["string","null"]},"entity_id":{"type":["string","null"]},"actor_type":{"type":"string"},"payload":{"type":"object","additionalProperties":{}}},"required":["id","event_uuid","event_type","occurred_at","brand_id","institution_id","entity_type","entity_id","actor_type","payload"]}}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/institution/applications":{"get":{"operationId":"getInstitutionApplications","summary":"The review queue","description":"Submissions awaiting or past review, with the brand, the screening run and any open task. Filter by `status`.\n\nRequired scope: `review:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"review:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","submitted","screening","needs_review","needs_info","approved","denied","withdrawn","expired","granted"]}}]}},"/v2/institution/applications/{submissionId}":{"get":{"operationId":"getInstitutionApplicationsBySubmissionId","summary":"One submission, licensor view","description":"Everything the reviewer sees: the frozen application, per-requirement findings with evidence, documents, and status history.\n\nRequired scope: `review:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"review:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postInstitutionApplicationsBySubmissionId","summary":"Decide a submission","description":"Approve, deny, or request more information (`info_note` is required for `request_info`). Deciding records a signed-in reviewer, so this route needs a session-backed principal; a plain institution key gets 401.\n\nRequired scope: `review:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"review:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","deny","request_info"]},"reason":{"type":"string","maxLength":4000},"info_note":{"type":"string","maxLength":4000}},"required":["decision"]}}}}}},"/v2/institution/applications/{submissionId}/findings/{findingId}":{"patch":{"operationId":"patchInstitutionApplicationsBySubmissionIdFindingsByFindingId","summary":"Confirm or override a screening finding","description":"Human judgement on one automated finding. `overridden` requires an `override_result`.\n\nRequired scope: `review:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"review:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"findingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"review_status":{"type":"string","enum":["confirmed","overridden"]},"override_result":{"type":"string","enum":["pass","fail","unknown","not_applicable"]},"review_note":{"type":["string","null"],"maxLength":2000}},"required":["review_status"]}}}}}},"/v2/institution/brands":{"get":{"operationId":"getInstitutionBrands","summary":"Brands with a relationship to the institution","description":"Every brand that has applied to, or holds a grant from, the institution, with submission and grant counts.\n\nRequired scope: `brands:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"brands:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"website_domain":{"type":["string","null"]},"submission_count":{"type":"integer"},"grant_count":{"type":"integer"},"active_grant_count":{"type":"integer"}},"required":["id","name","slug","website_domain","submission_count","grant_count","active_grant_count"]}}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}]}},"/v2/institution/catalog":{"get":{"operationId":"getInstitutionCatalog","summary":"The rights-matrix catalog","description":"Product categories, logo groups with previews, licences, and the channel taxonomy — everything needed to compose grant lines and rates.\n\nRequired scope: `grants:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"post":{"operationId":"postInstitutionCatalog","summary":"Import the platform category template","description":"Copies the standard product-category tree into the institution. Idempotent: it returns how many categories were added, zero on a repeat call.\n\nRequired scope: `grants:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"imported":{"type":"integer"}},"required":["imported"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/institution/grants":{"get":{"operationId":"getInstitutionGrants","summary":"List grants issued by the institution","description":"Grants with the licensee brand, status and approved line count. Filter by `status`.\n\nRequired scope: `grants:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":40}}]},"post":{"operationId":"postInstitutionGrants","summary":"Issue a draft grant","description":"Creates a draft grant: one rights line per cell of the matrix (a null dimension means 'all'), plus a grant-scoped royalty rate schedule. When `submission_id` is given the submission must already be approved.\n\nRequired scope: `grants:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand_id":{"type":"string","format":"uuid"},"submission_id":{"type":["string","null"],"format":"uuid"},"license_id":{"type":["string","null"],"format":"uuid"},"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"effective_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"territory_code":{"type":"string","minLength":2,"maxLength":8,"default":"US"},"terms":{"type":"object","properties":{"minimum_guarantee_usd":{"type":["number","null"],"minimum":0},"advance_usd":{"type":["number","null"],"minimum":0},"reporting_cadence":{"type":"string","enum":["monthly","quarterly","annual"]},"audit_rights":{"type":"boolean"},"notes":{"type":["string","null"],"maxLength":4000}},"default":{}},"tier_basis":{"type":"string","enum":["none","brand_ttm_revenue","contract_year_sales","grant_cumulative_sales"],"default":"none"},"basis":{"type":"string","enum":["net_sales","gross_sales","per_unit"],"default":"net_sales"},"lines":{"type":"array","items":{"type":"object","properties":{"channel_class_code":{"type":["string","null"],"enum":["direct","wholesale","marketplace"]},"channel_code":{"type":["string","null"],"enum":["CAMP","SMC","SMT","REST","DPT","ITC","AMP","BDPT","RRET","SCWC","GLFS","TDLR","GDC","SGSS","OPC"]},"product_category_id":{"type":["string","null"],"format":"uuid"},"logo_group_id":{"type":["string","null"],"format":"uuid"},"logo_id":{"type":["string","null"],"format":"uuid"},"territory_code":{"type":["string","null"],"minLength":2,"maxLength":8},"notes":{"type":["string","null"],"maxLength":500}}},"minItems":1,"maxItems":200},"rates":{"type":"array","items":{"type":"object","properties":{"channel_class_code":{"type":["string","null"],"enum":["direct","wholesale","marketplace"]},"channel_code":{"type":["string","null"],"enum":["CAMP","SMC","SMT","REST","DPT","ITC","AMP","BDPT","RRET","SCWC","GLFS","TDLR","GDC","SGSS","OPC"]},"product_category_id":{"type":["string","null"],"format":"uuid"},"logo_group_id":{"type":["string","null"],"format":"uuid"},"logo_id":{"type":["string","null"],"format":"uuid"},"rate_pct":{"type":["number","null"],"minimum":0,"maximum":100},"flat_amount":{"type":["number","null"],"minimum":0},"tiers":{"type":"array","items":{"type":"object","properties":{"tier_min":{"type":["number","null"],"minimum":0,"default":null},"tier_max":{"type":["number","null"],"minimum":0,"default":null},"rate_pct":{"type":"number","minimum":0,"maximum":100}},"required":["rate_pct"]},"maxItems":10},"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"effective_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"priority":{"type":"integer","minimum":-100,"maximum":100,"default":0},"notes":{"type":["string","null"],"maxLength":500}}},"maxItems":200,"default":[]}},"required":["brand_id","lines"]}}}}}},"/v2/institution/grants/{grantId}":{"get":{"operationId":"getInstitutionGrantsByGrantId","summary":"One grant, or a rate preview","description":"Returns the grant with lines and schedule. With `preview=1` it instead resolves the royalty rate a sale would receive under this grant for the given date, channel, category, logo and tier value.\n\nRequired scope: `grants:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"preview","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"sale_date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"channel_class_code","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"channel_code","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"product_category_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"logo_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"tier_value","in":"query","required":false,"schema":{"type":"number"}}]},"post":{"operationId":"postInstitutionGrantsByGrantId","summary":"Move a grant through its lifecycle","description":"`send_for_signature`, `sign`, `suspend`, `reinstate`, `terminate` or `back_to_draft`. The allowed actions depend on the current status.\n\nRequired scope: `grants:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["send_for_signature","sign","suspend","reinstate","terminate","back_to_draft"]},"party":{"type":"string","enum":["brand","institution"]}},"required":["action"]}}}}},"patch":{"operationId":"patchInstitutionGrantsByGrantId","summary":"Amend a grant","description":"Add, remove or revoke rights lines and replace the rate schedule. Only draft and pending-signature grants are editable.\n\nRequired scope: `grants:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"grants:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"effective_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"territory_code":{"type":"string","minLength":2,"maxLength":8},"terms":{"type":"object","properties":{"minimum_guarantee_usd":{"type":["number","null"],"minimum":0},"advance_usd":{"type":["number","null"],"minimum":0},"reporting_cadence":{"type":"string","enum":["monthly","quarterly","annual"]},"audit_rights":{"type":"boolean"},"notes":{"type":["string","null"],"maxLength":4000}},"default":{}},"license_id":{"type":["string","null"],"format":"uuid"},"add_lines":{"type":"array","items":{"type":"object","properties":{"channel_class_code":{"type":["string","null"],"enum":["direct","wholesale","marketplace"]},"channel_code":{"type":["string","null"],"enum":["CAMP","SMC","SMT","REST","DPT","ITC","AMP","BDPT","RRET","SCWC","GLFS","TDLR","GDC","SGSS","OPC"]},"product_category_id":{"type":["string","null"],"format":"uuid"},"logo_group_id":{"type":["string","null"],"format":"uuid"},"logo_id":{"type":["string","null"],"format":"uuid"},"territory_code":{"type":["string","null"],"minLength":2,"maxLength":8},"notes":{"type":["string","null"],"maxLength":500}}},"maxItems":200},"remove_line_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":200},"revoke_line_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":200},"replace_rates":{"type":"array","items":{"type":"object","properties":{"channel_class_code":{"type":["string","null"],"enum":["direct","wholesale","marketplace"]},"channel_code":{"type":["string","null"],"enum":["CAMP","SMC","SMT","REST","DPT","ITC","AMP","BDPT","RRET","SCWC","GLFS","TDLR","GDC","SGSS","OPC"]},"product_category_id":{"type":["string","null"],"format":"uuid"},"logo_group_id":{"type":["string","null"],"format":"uuid"},"logo_id":{"type":["string","null"],"format":"uuid"},"rate_pct":{"type":["number","null"],"minimum":0,"maximum":100},"flat_amount":{"type":["number","null"],"minimum":0},"tiers":{"type":"array","items":{"type":"object","properties":{"tier_min":{"type":["number","null"],"minimum":0,"default":null},"tier_max":{"type":["number","null"],"minimum":0,"default":null},"rate_pct":{"type":"number","minimum":0,"maximum":100}},"required":["rate_pct"]},"maxItems":10},"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"effective_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"priority":{"type":"integer","minimum":-100,"maximum":100,"default":0},"notes":{"type":["string","null"],"maxLength":500}}},"maxItems":200},"tier_basis":{"type":"string","enum":["none","brand_ttm_revenue","contract_year_sales","grant_cumulative_sales"]},"basis":{"type":"string","enum":["net_sales","gross_sales","per_unit"]}}}}}}}},"/v2/institution/intake":{"get":{"operationId":"getInstitutionIntake","summary":"Read the licensing intake profile","description":"Whether the institution is accepting applications, its review SLA, the public checklist flag, contact email and terms URL.\n\nRequired scope: `requirements:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"institution_id":{"type":"string","format":"uuid"},"accepting_applications":{"type":"boolean"},"public_checklist_enabled":{"type":"boolean"},"review_sla_days":{"type":"integer"},"contact_email":{"type":["string","null"]},"terms_url":{"type":["string","null"]},"auto_approve_mode":{"type":"string","enum":["manual","soft","hard"]},"auto_deny_mode":{"type":"string","enum":["manual","soft","hard"]}},"required":["institution_id","accepting_applications","public_checklist_enabled","review_sla_days","contact_email","terms_url","auto_approve_mode","auto_deny_mode"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"patch":{"operationId":"patchInstitutionIntake","summary":"Update the licensing intake profile","description":"Partial update. Setting `accepting_applications` to false closes intake without touching existing submissions.\n\nRequired scope: `requirements:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"institution_id":{"type":"string","format":"uuid"},"accepting_applications":{"type":"boolean"},"public_checklist_enabled":{"type":"boolean"},"review_sla_days":{"type":"integer"},"contact_email":{"type":["string","null"]},"terms_url":{"type":["string","null"]},"auto_approve_mode":{"type":"string","enum":["manual","soft","hard"]},"auto_deny_mode":{"type":"string","enum":["manual","soft","hard"]}},"required":["institution_id","accepting_applications","public_checklist_enabled","review_sla_days","contact_email","terms_url","auto_approve_mode","auto_deny_mode"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accepting_applications":{"type":"boolean"},"public_checklist_enabled":{"type":"boolean"},"review_sla_days":{"type":"integer","minimum":1,"maximum":365},"contact_email":{"type":["string","null"],"format":"email"},"terms_url":{"type":["string","null"],"format":"uri"},"auto_approve_mode":{"type":"string","enum":["manual","soft","hard"]},"auto_deny_mode":{"type":"string","enum":["manual","soft","hard"]}}}}}}}},"/v2/institution/requirements":{"get":{"operationId":"getInstitutionRequirements","summary":"List licensing requirements","description":"The institution's requirement set. Inactive requirements are hidden unless `include_inactive` is set.\n\nRequired scope: `requirements:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","default":false}}]},"put":{"operationId":"putInstitutionRequirements","summary":"Create or update a requirement","description":"Upsert by `id` (omit it to create). The `config` shape is validated against the requirement type's rule kind. Changing requirements re-screens every open submission.\n\nRequired scope: `requirements:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"requirement_type_code":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","additionalProperties":{},"default":{}},"enforcement":{"type":"string","enum":["hard_gate","soft_signal"]},"weight":{"type":"number","minimum":0,"maximum":999},"is_public":{"type":"boolean"},"display_label":{"type":["string","null"],"maxLength":160},"help_text":{"type":["string","null"],"maxLength":2000},"sort_order":{"type":["integer","null"]},"is_active":{"type":"boolean"}},"required":["requirement_type_code","enforcement"]}}}}}},"/v2/institution/requirements/{requirementId}":{"get":{"operationId":"getInstitutionRequirementsByRequirementId","summary":"Read one requirement","description":"A single requirement including inactive ones, with its requirement type expanded.\n\nRequired scope: `requirements:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"requirementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]},"put":{"operationId":"putInstitutionRequirementsByRequirementId","summary":"Update one requirement","description":"Same body as the collection upsert; the path id wins over any `id` in the body.\n\nRequired scope: `requirements:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"requirementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"requirement_type_code":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","additionalProperties":{},"default":{}},"enforcement":{"type":"string","enum":["hard_gate","soft_signal"]},"weight":{"type":"number","minimum":0,"maximum":999},"is_public":{"type":"boolean"},"display_label":{"type":["string","null"],"maxLength":160},"help_text":{"type":["string","null"],"maxLength":2000},"sort_order":{"type":["integer","null"]},"is_active":{"type":"boolean"}},"required":["requirement_type_code","enforcement"]}}}}},"delete":{"operationId":"deleteInstitutionRequirementsByRequirementId","summary":"Delete a requirement","description":"Removes the requirement and re-screens open submissions that were judged against it.\n\nRequired scope: `requirements:write`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"requirements:write","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"requirementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/v2/institution/revenue":{"get":{"operationId":"getInstitutionRevenue","summary":"Royalty revenue summary","description":"Attributed net sales and royalties in the window, grouped by brand, channel or category. Defaults to the trailing twelve months.\n\nRequired scope: `revenue:read`.","tags":["institution"],"security":[{"apiKey":[]}],"x-scope":"revenue:read","x-principal":"institution","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"institution_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string"}}]}},"/v2/me":{"get":{"operationId":"getMe","summary":"Identify the caller","description":"Returns the principal behind the API key (brand, institution, super_admin or user), the key id, the granted scopes, and the tenant record. Call this first to discover which half of the API a key can reach.","tags":["core"],"security":[{"apiKey":[]}],"x-scope":null,"x-principal":"any","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"principal_type":{"type":"string","enum":["brand","institution","super_admin","user"]},"key_id":{"type":["string","null"],"format":"uuid"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["principal_type","key_id","scopes"]}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/openapi.json":{"get":{"operationId":"getOpenapiJson","summary":"This OpenAPI 3.1 document","description":"The machine-readable description of every v2 route. Served without authentication so agents can plan a call before they hold a key.","tags":["core"],"security":[],"x-scope":null,"x-principal":"public","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}},"required":["data"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, or the tenant does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}