{"openapi":"3.1.0","info":{"title":"CARM Creative Asset Rating API","version":"1.0.2","description":"Versioned catalogue rating, valuation, and certificate API for creative IP.\n\nPush a `catalogue` object, request a rating, then a valuation, then — once legal evidence\nis authority-verified — a certificate. Every example on this page is generated from the\nlive methodology engine against the CARM-1.0.2 worked example, so it is never hand-typed\nand never drifts from what the API actually returns.","contact":{"name":"CARM","url":"https://github.com/king-tiff/carm"}},"servers":[{"url":"/v1","description":"Current environment"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Catalogues","description":"Create or update the source catalogue object."},{"name":"Ratings","description":"Deterministic CARM score and M/L/T dimensions."},{"name":"Valuations","description":"MLT Method appraisal, confidence band, and facility sizing."},{"name":"Certificates","description":"Human-reviewed, publicly verifiable valuation certificates."},{"name":"Verification","description":"Public, unauthenticated certificate verification."}],"paths":{"/catalogues/{external_id}":{"put":{"tags":["Catalogues"],"summary":"Create or update a catalogue","description":"Idempotent by `external_id` — the caller's own identifier. Re-sending the same `external_id` updates the existing catalogue and increments its revision.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"example":"worked_example_gospel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalogue"},"example":{"external_id":"worked_example_gospel","profile":{"artist_name":"East African Gospel Catalogue","title":"East African Gospel Catalogue","jurisdiction":"TZ","currency":"USD","track_count":36,"catalogue_age_months":21,"catalogue_type":"growing"},"market":{"monthly_streams":5571051,"stream_growth_pct":33.5,"sync_appeal":0,"diaspora_share_pct":88,"sync_placements":0,"cultural_impact":50,"active_export_markets":50,"discoverability_index":0,"playlist_adds":0},"technology":{"isrc_coverage_pct":100,"platform_count":31,"metadata_quality":85},"legal":{"copyright_registration_pct":0,"chain_of_title":"documented","pro_coverage_pct":0,"encumbrances":1,"evidence":[{"field":"chain_of_title","authority":"TUNEPESA","evidence":"self_declared"}]},"revenue":{"digital_annual":15253,"streaming_annual":2294,"publishing_annual":0,"neighbouring_annual":0,"mechanical_annual":0,"sync_annual":0},"prior_claims":[{"type":"distributor_advance","outstanding":5311,"seniority":"senior"}],"valuation":{"pessimistic_pct":-15,"base_case_pct":0,"optimistic_pct":15,"long_run_growth_pct":0,"asset_class_premium_pct":5.5,"cultural_factors":{"diaspora":0,"genre_momentum":0,"cross_cultural":0,"social_resonance":0},"relief_rate_pct":10}}}}},"responses":{"200":{"description":"Catalogue saved","content":{"application/json":{"example":{"catalogue_id":"cat_01J8QK6Z3F8X9V2N4T7Y6WABCD","external_id":"worked_example_gospel","revision":1,"methodology_version":"CARM-1.0.2"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Invalid API key"}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"validation_error","message":"market.diaspora_share_pct must be between 0 and 100","field":"market.diaspora_share_pct"}}}}}}}},"/ratings":{"post":{"tags":["Ratings"],"summary":"Rate a catalogue","description":"Synchronous. Pass a `catalogue_id` from a prior `PUT`, or an inline `catalogue` object. Legal evidence is read from the catalogue's authority-verified evidence registry, not just the inline payload.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatingRequest"},"example":{"catalogue_id":"cat_01J8QK6Z3F8X9V2N4T7Y6WABCD"}}}},"responses":{"200":{"description":"Rating result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatingResponse"},"example":{"rating_id":"rt_01J8QK6Z3F8X9V2N4T7Y6WABCD","catalogue_id":"cat_01J8QK6Z3F8X9V2N4T7Y6WABCD","external_id":"worked_example_gospel","methodology_version":"CARM-1.0.2","carm_score":57.861,"band":"C","band_label":"Developing","dimensions":{"market":59.973,"legal":35.25,"technology":76.25},"mlt_multiplier":1.031446,"indicative_ltv_pct":32.337,"discount_rate_pct":9.87,"legal_status":"provisional","created_at":"2026-06-09T08:12:55Z"}}}},"404":{"description":"Catalogue not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Catalogue not found"}}}}},"422":{"description":"catalogue_id or catalogue is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"validation_error","message":"catalogue_id or catalogue is required"}}}}}}}},"/valuations":{"post":{"tags":["Valuations"],"summary":"Value a rated catalogue","description":"Synchronous. `net_facility` already nets `prior_claims` from the maximum facility — use it, not `max_facility`, when sizing any financing offer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationRequest"},"example":{"rating_id":"rt_01J8QK6Z3F8X9V2N4T7Y6WABCD"}}}},"responses":{"200":{"description":"Valuation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResponse"},"example":{"valuation_id":"vl_01J8QK6Z3F8X9V2N4T7Y6WABCD","rating_id":"rt_01J8QK6Z3F8X9V2N4T7Y6WABCD","methodology_version":"CARM-1.0.2","currency":"USD","approaches":{"income":85793.01,"market":114592.88,"relief":8579.3},"raw_value":85730.9,"appraised_value":88426.8,"mlt_multiplier":1.031446,"confidence_band_pct":28,"value_low":63667.29,"value_high":113186.3,"prior_claims_total":5311,"indicative_ltv_pct":32.337,"max_facility":28594.57,"net_facility":23283.57}}}},"404":{"description":"Rating not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Rating not found"}}}}}}}},"/certificates":{"post":{"tags":["Certificates"],"summary":"Request a certificate","description":"Certificates require qualified human sign-off, so issuance is asynchronous: this call returns a `preliminary` record immediately. Poll the record, or watch for a `certificate.issued` webhook, to learn when it becomes `final`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateRequest"},"example":{"valuation_id":"vl_01J8QK6Z3F8X9V2N4T7Y6WABCD","licensee":"TunePesa"}}}},"responses":{"202":{"description":"Certificate queued for review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateResponse"},"example":{"certificate_id":"ct_01J8QK6Z3F8X9V2N4T7Y6WABCD","status":"preliminary","reference":"CARM-2026-08842","pdf_url":null,"content_hash":"61605c0809580744c0a4ad573873438a9b69f540117ef7795fe452e48427663d"}}}},"404":{"description":"Valuation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Valuation not found"}}}}}}}},"/verify/{reference}":{"get":{"tags":["Verification"],"summary":"Publicly verify a certificate","description":"No API key required — this is the URL embedded in the QR code on every certificate, and must be reachable by any credit officer with a phone.","security":[],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"},"example":"CARM-2026-08842"}],"responses":{"200":{"description":"Certificate verification record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRecord"},"example":{"reference":"CARM-2026-08842","status":"preliminary","methodology_version":"CARM-1.0.2","content_hash":"61605c0809580744c0a4ad573873438a9b69f540117ef7795fe452e48427663d","signed_by":null,"issued_at":"2026-06-09T08:12:55Z","valid_until":null,"subject":"East African Gospel Catalogue","artist_name":"East African Gospel Catalogue","jurisdiction":"TZ","carm_score":57.861,"band":"C","appraised_value":88426.8,"confidence_band_pct":28,"indicative_ltv_pct":32.337,"net_facility":23283.57}}}},"404":{"description":"Certificate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Certificate not found"}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Per-workspace bearer key, e.g. `Authorization: Bearer sk_live_...`."}},"schemas":{"Catalogue":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":160},"profile":{"type":"object","properties":{"artist_name":{"type":"string","minLength":1,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":240},"jurisdiction":{"type":"string","minLength":2,"maxLength":8},"currency":{"type":"string","minLength":3,"maxLength":3},"track_count":{"default":0,"type":"integer","minimum":0,"maximum":100000},"catalogue_age_months":{"default":0,"type":"integer","minimum":0,"maximum":1200},"catalogue_type":{"default":"growing","type":"string","enum":["established","growing","early","sync","publishing"]}},"required":["artist_name","title","jurisdiction"]},"market":{"default":{"monthly_streams":0,"stream_growth_pct":0,"sync_appeal":0,"diaspora_share_pct":0,"sync_placements":0,"active_export_markets":0,"discoverability_index":0,"playlist_adds":0},"type":"object","properties":{"monthly_streams":{"default":0,"type":"number","minimum":0},"stream_growth_pct":{"default":0,"type":"number","minimum":-100,"maximum":1000},"sync_appeal":{"default":0,"type":"number","minimum":0,"maximum":100},"diaspora_share_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"sync_placements":{"default":0,"type":"number","minimum":0},"cultural_impact":{"type":"number","minimum":0,"maximum":100},"active_export_markets":{"default":0,"type":"number","minimum":0,"maximum":250},"discoverability_index":{"default":0,"type":"number","minimum":0,"maximum":100},"playlist_adds":{"default":0,"type":"number","minimum":0}}},"technology":{"default":{"isrc_coverage_pct":0,"platform_count":0,"metadata_quality":0},"type":"object","properties":{"isrc_coverage_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"platform_count":{"default":0,"type":"number","minimum":0,"maximum":1000},"metadata_quality":{"default":0,"type":"number","minimum":0,"maximum":100}}},"legal":{"default":{"copyright_registration_pct":0,"chain_of_title":"undocumented","pro_coverage_pct":0,"encumbrances":0,"evidence":[]},"type":"object","properties":{"copyright_registration_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"chain_of_title":{"default":"undocumented","type":"string","enum":["undocumented","documented","clean"]},"pro_coverage_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"encumbrances":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"evidence":{"default":[],"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"authority":{"type":"string","enum":["COSOTA","COSOZA","BASATA","TUNEPESA","SELF_DECLARED"]},"evidence":{"type":"string","enum":["cosota_clearance_cert","cosota_registration","cosota_membership","basata_registration","sighted_agreement","self_declared"]},"reference":{"type":"string"},"verified_at":{"type":"string"},"reverify_after_months":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["field","authority","evidence"]}}}},"revenue":{"default":{"digital_annual":0,"streaming_annual":0,"publishing_annual":0,"neighbouring_annual":0,"mechanical_annual":0,"sync_annual":0},"type":"object","properties":{"digital_annual":{"default":0,"type":"number","minimum":0},"streaming_annual":{"default":0,"type":"number","minimum":0},"publishing_annual":{"default":0,"type":"number","minimum":0},"neighbouring_annual":{"default":0,"type":"number","minimum":0},"mechanical_annual":{"default":0,"type":"number","minimum":0},"sync_annual":{"default":0,"type":"number","minimum":0}}},"prior_claims":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1},"outstanding":{"type":"number","minimum":0},"seniority":{"default":"senior","type":"string","enum":["senior","pari_passu","junior"]}},"required":["type","outstanding"]}},"valuation":{"default":{"pessimistic_pct":-15,"base_case_pct":0,"optimistic_pct":15,"long_run_growth_pct":0,"asset_class_premium_pct":5.5,"cultural_factors":{"diaspora":0,"genre_momentum":0,"cross_cultural":0,"social_resonance":0},"relief_rate_pct":10},"type":"object","properties":{"pessimistic_pct":{"default":-15,"type":"number","minimum":-100,"maximum":500},"base_case_pct":{"default":0,"type":"number","minimum":-100,"maximum":500},"optimistic_pct":{"default":15,"type":"number","minimum":-100,"maximum":500},"long_run_growth_pct":{"default":0,"type":"number","minimum":-100,"maximum":100},"asset_class_premium_pct":{"default":5.5,"type":"number","minimum":0,"maximum":100},"market_multiple":{"type":"number","minimum":0,"maximum":100},"cultural_factors":{"default":{"diaspora":0,"genre_momentum":0,"cross_cultural":0,"social_resonance":0},"type":"object","properties":{"diaspora":{"default":0,"type":"number","minimum":0,"maximum":100},"genre_momentum":{"default":0,"type":"number","minimum":0,"maximum":100},"cross_cultural":{"default":0,"type":"number","minimum":0,"maximum":100},"social_resonance":{"default":0,"type":"number","minimum":0,"maximum":100}}},"relief_rate_pct":{"default":10,"type":"number","minimum":0,"maximum":100}}}},"required":["external_id","profile"]},"RatingRequest":{"type":"object","properties":{"catalogue_id":{"type":"string","description":"A catalogue_id returned from a prior PUT /catalogues/{external_id}."},"catalogue":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":160},"profile":{"type":"object","properties":{"artist_name":{"type":"string","minLength":1,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":240},"jurisdiction":{"type":"string","minLength":2,"maxLength":8},"currency":{"type":"string","minLength":3,"maxLength":3},"track_count":{"default":0,"type":"integer","minimum":0,"maximum":100000},"catalogue_age_months":{"default":0,"type":"integer","minimum":0,"maximum":1200},"catalogue_type":{"default":"growing","type":"string","enum":["established","growing","early","sync","publishing"]}},"required":["artist_name","title","jurisdiction"]},"market":{"default":{"monthly_streams":0,"stream_growth_pct":0,"sync_appeal":0,"diaspora_share_pct":0,"sync_placements":0,"active_export_markets":0,"discoverability_index":0,"playlist_adds":0},"type":"object","properties":{"monthly_streams":{"default":0,"type":"number","minimum":0},"stream_growth_pct":{"default":0,"type":"number","minimum":-100,"maximum":1000},"sync_appeal":{"default":0,"type":"number","minimum":0,"maximum":100},"diaspora_share_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"sync_placements":{"default":0,"type":"number","minimum":0},"cultural_impact":{"type":"number","minimum":0,"maximum":100},"active_export_markets":{"default":0,"type":"number","minimum":0,"maximum":250},"discoverability_index":{"default":0,"type":"number","minimum":0,"maximum":100},"playlist_adds":{"default":0,"type":"number","minimum":0}}},"technology":{"default":{"isrc_coverage_pct":0,"platform_count":0,"metadata_quality":0},"type":"object","properties":{"isrc_coverage_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"platform_count":{"default":0,"type":"number","minimum":0,"maximum":1000},"metadata_quality":{"default":0,"type":"number","minimum":0,"maximum":100}}},"legal":{"default":{"copyright_registration_pct":0,"chain_of_title":"undocumented","pro_coverage_pct":0,"encumbrances":0,"evidence":[]},"type":"object","properties":{"copyright_registration_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"chain_of_title":{"default":"undocumented","type":"string","enum":["undocumented","documented","clean"]},"pro_coverage_pct":{"default":0,"type":"number","minimum":0,"maximum":100},"encumbrances":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"evidence":{"default":[],"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"authority":{"type":"string","enum":["COSOTA","COSOZA","BASATA","TUNEPESA","SELF_DECLARED"]},"evidence":{"type":"string","enum":["cosota_clearance_cert","cosota_registration","cosota_membership","basata_registration","sighted_agreement","self_declared"]},"reference":{"type":"string"},"verified_at":{"type":"string"},"reverify_after_months":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["field","authority","evidence"]}}}},"revenue":{"default":{"digital_annual":0,"streaming_annual":0,"publishing_annual":0,"neighbouring_annual":0,"mechanical_annual":0,"sync_annual":0},"type":"object","properties":{"digital_annual":{"default":0,"type":"number","minimum":0},"streaming_annual":{"default":0,"type":"number","minimum":0},"publishing_annual":{"default":0,"type":"number","minimum":0},"neighbouring_annual":{"default":0,"type":"number","minimum":0},"mechanical_annual":{"default":0,"type":"number","minimum":0},"sync_annual":{"default":0,"type":"number","minimum":0}}},"prior_claims":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1},"outstanding":{"type":"number","minimum":0},"seniority":{"default":"senior","type":"string","enum":["senior","pari_passu","junior"]}},"required":["type","outstanding"]}},"valuation":{"default":{"pessimistic_pct":-15,"base_case_pct":0,"optimistic_pct":15,"long_run_growth_pct":0,"asset_class_premium_pct":5.5,"cultural_factors":{"diaspora":0,"genre_momentum":0,"cross_cultural":0,"social_resonance":0},"relief_rate_pct":10},"type":"object","properties":{"pessimistic_pct":{"default":-15,"type":"number","minimum":-100,"maximum":500},"base_case_pct":{"default":0,"type":"number","minimum":-100,"maximum":500},"optimistic_pct":{"default":15,"type":"number","minimum":-100,"maximum":500},"long_run_growth_pct":{"default":0,"type":"number","minimum":-100,"maximum":100},"asset_class_premium_pct":{"default":5.5,"type":"number","minimum":0,"maximum":100},"market_multiple":{"type":"number","minimum":0,"maximum":100},"cultural_factors":{"default":{"diaspora":0,"genre_momentum":0,"cross_cultural":0,"social_resonance":0},"type":"object","properties":{"diaspora":{"default":0,"type":"number","minimum":0,"maximum":100},"genre_momentum":{"default":0,"type":"number","minimum":0,"maximum":100},"cross_cultural":{"default":0,"type":"number","minimum":0,"maximum":100},"social_resonance":{"default":0,"type":"number","minimum":0,"maximum":100}}},"relief_rate_pct":{"default":10,"type":"number","minimum":0,"maximum":100}}}},"required":["external_id","profile"],"description":"An inline catalogue object, if not previously saved."}}},"RatingResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rating_id":{"type":"string"},"catalogue_id":{"type":"string"},"external_id":{"type":"string"},"methodology_version":{"type":"string"},"carm_score":{"type":"number"},"band":{"type":"string","enum":["A","B","C","D"]},"band_label":{"type":"string"},"dimensions":{"type":"object","properties":{"market":{"type":"number"},"legal":{"type":"number"},"technology":{"type":"number"}},"required":["market","legal","technology"]},"mlt_multiplier":{"type":"number"},"indicative_ltv_pct":{"type":"number"},"discount_rate_pct":{"type":"number"},"legal_status":{"type":"string","enum":["provisional","verified"]},"created_at":{"type":"string"}},"required":["rating_id","catalogue_id","external_id","methodology_version","carm_score","band","band_label","dimensions","mlt_multiplier","indicative_ltv_pct","discount_rate_pct","legal_status","created_at"]},"ValuationRequest":{"type":"object","required":["rating_id"],"properties":{"rating_id":{"type":"string"}}},"ValuationResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"valuation_id":{"type":"string"},"rating_id":{"type":"string"},"methodology_version":{"type":"string"},"currency":{"type":"string"},"approaches":{"type":"object","properties":{"income":{"type":"number"},"market":{"type":"number"},"relief":{"type":"number"}},"required":["income","market","relief"]},"raw_value":{"type":"number"},"appraised_value":{"type":"number"},"mlt_multiplier":{"type":"number"},"confidence_band_pct":{"type":"number"},"value_low":{"type":"number"},"value_high":{"type":"number"},"prior_claims_total":{"type":"number"},"indicative_ltv_pct":{"type":"number"},"max_facility":{"type":"number"},"net_facility":{"type":"number"}},"required":["valuation_id","rating_id","methodology_version","currency","approaches","raw_value","appraised_value","mlt_multiplier","confidence_band_pct","value_low","value_high","prior_claims_total","indicative_ltv_pct","max_facility","net_facility"]},"CertificateRequest":{"type":"object","required":["valuation_id"],"properties":{"valuation_id":{"type":"string"},"licensee":{"type":"string","description":"Optional white-label licensee name printed on the certificate."}}},"CertificateResponse":{"type":"object","properties":{"certificate_id":{"type":"string"},"status":{"type":"string","enum":["preliminary","review","final","rejected","revoked"]},"reference":{"type":"string"},"pdf_url":{"type":["string","null"]},"content_hash":{"type":"string"}}},"VerifyRecord":{"type":"object","properties":{"reference":{"type":"string"},"status":{"type":"string","enum":["preliminary","review","final","rejected","revoked"]},"methodology_version":{"type":"string"},"content_hash":{"type":"string"},"signed_by":{"type":["string","null"]},"issued_at":{"type":"string","format":"date-time"},"valid_until":{"type":["string","null"],"format":"date-time"},"subject":{"type":"string"},"artist_name":{"type":"string"},"jurisdiction":{"type":"string"},"carm_score":{"type":"number"},"band":{"type":"string","enum":["A","B","C","D"]},"appraised_value":{"type":"number"},"confidence_band_pct":{"type":"number"},"indicative_ltv_pct":{"type":"number"},"net_facility":{"type":"number"}}},"Error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}