{ "openapi": "3.1.0", "info": { "title": "FilmRightsProof API", "version": "1.1.1", "description": "Public-record film/TV rights intelligence for agent delegation. FilmRightsProof combines a reproducible U.S. Copyright Office bulk substrate ending June 27, 2025 with bounded current Copyright Public Records System verification when available. Every trace exposes exact search/freshness limits and is less than a legal ownership or clearance opinion." }, "servers": [ { "url": "https://filmrightsproof.davisvillelabs.com" } ], "paths": { "/v1/capabilities": { "get": { "operationId": "capabilities", "responses": { "200": { "description": "Capability, commerce, coverage and result-contract metadata" } } } }, "/v1/search": { "post": { "operationId": "searchPublicRecords", "summary": "Free bounded candidate-record search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Identify the requested film, television title, or underlying creative work. Title is required; creator, year, and workType help disambiguate; limit only bounds candidate inspection.", "additionalProperties": false, "required": [ "title" ], "examples": [ { "title": "The Godfather", "year": 1972, "workType": "motion picture", "limit": 10 } ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "example": "The Godfather" }, "creator": { "type": "string", "maxLength": 300, "example": "Francis Ford Coppola" }, "year": { "type": "integer", "minimum": 1700, "maximum": 2100, "example": 1972 }, "workType": { "type": "string", "maxLength": 120, "example": "motion picture" }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "example": 10 } } } } } }, "responses": { "200": { "description": "Candidate public records with per-request freshness state", "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "query", "candidates", "coverage", "freshness", "evidenceGaps", "legalNotice" ], "properties": { "schemaVersion": { "const": "public-record-search.v1" }, "query": { "type": "object" }, "candidates": { "type": "array", "items": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "registrationNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicationYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "workType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "coverage": { "type": "object" }, "freshness": { "type": "object", "required": [ "schemaVersion", "currentLookupAttempted", "currentLookupVerified", "currentEvidenceUsable", "transportStatus", "parsingStatus", "evidenceStatus", "observation", "fallback" ], "properties": { "schemaVersion": { "const": "filmrightsproof-freshness.v2" }, "currentLookupAttempted": { "type": "boolean" }, "currentLookupVerified": { "type": "boolean", "description": "Narrow compatibility summary. True only when the bounded current lookup completed without normalization rejection; it does not mean exhaustive coverage." }, "currentEvidenceUsable": { "type": "boolean" }, "transportStatus": { "enum": [ "succeeded", "failed", "not_attempted" ] }, "parsingStatus": { "enum": [ "succeeded", "failed", "not_completed", "not_attempted" ] }, "evidenceStatus": { "enum": [ "usable", "usable_no_qualifying_match", "partial", "partial_no_qualifying_match", "zero_hits", "normalization_failed", "unavailable" ] }, "queryStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queryCompletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "observedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "searchScope": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "observation": { "type": "object" }, "fallback": { "type": "object" }, "sourceMix": { "type": "object" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": true }, "evidenceGaps": { "type": "array", "items": { "type": "string" } }, "legalNotice": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/v1/trace": { "post": { "operationId": "tracePublicRights", "summary": "Paid specialist public-record rights reconciliation", "description": "Use for a structured film/TV public-record rights dossier rather than a simple record lookup. Resolves work identity where supportable, reconciles maintained evidence, emits only source-supported relationships, and exposes ambiguity, provenance, search bounds and freshness. Does not provide legal clearance or definitive ownership.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Identify the requested film, television title, or underlying creative work. Title is required; creator, year, and workType help disambiguate; limit only bounds candidate inspection.", "additionalProperties": false, "required": [ "title" ], "examples": [ { "title": "The Godfather", "year": 1972, "workType": "motion picture", "limit": 10 } ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "example": "The Godfather" }, "creator": { "type": "string", "maxLength": 300, "example": "Francis Ford Coppola" }, "year": { "type": "integer", "minimum": 1700, "maximum": 2100, "example": 1972 }, "workType": { "type": "string", "maxLength": 120, "example": "motion picture" }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "example": 10 } } } } } }, "responses": { "200": { "description": "Canonical trace-public-rights.v1 result", "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "operation", "traceId", "dossierId", "status", "query", "canonicalRequest", "candidates", "records", "evidence", "normalizedParties", "edges", "provenance", "freshness", "coverage", "unresolvedQuestions", "nonInferences", "evidenceGaps", "limitations", "methods", "state", "legalNotice" ], "properties": { "schemaVersion": { "const": "trace-public-rights.v1" }, "operation": { "const": "trace_public_rights" }, "traceId": { "type": "string" }, "dossierId": { "type": "string" }, "status": { "enum": [ "recorded_lineage_found", "partial_recorded_lineage", "ambiguous_work_identity", "no_match_within_search_scope", "insufficient_public_evidence" ] }, "query": { "type": "object" }, "canonicalRequest": { "type": "object" }, "resolvedWork": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "candidates": { "type": "array", "items": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "registrationNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicationYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "workType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "required": [ "id", "recordType", "title", "source" ], "properties": { "id": { "type": "string" }, "recordType": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object" } }, "additionalProperties": true } }, "evidence": { "type": "object", "required": [ "registrations", "renewals", "recordations", "terminations", "cancellations" ], "properties": { "registrations": { "type": "array", "items": { "type": "object", "required": [ "id", "recordType", "title", "source" ], "properties": { "id": { "type": "string" }, "recordType": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object" } }, "additionalProperties": true } }, "renewals": { "type": "array", "items": { "type": "object", "required": [ "id", "recordType", "title", "source" ], "properties": { "id": { "type": "string" }, "recordType": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object" } }, "additionalProperties": true } }, "recordations": { "type": "array", "items": { "type": "object", "required": [ "id", "recordType", "title", "source" ], "properties": { "id": { "type": "string" }, "recordType": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object" } }, "additionalProperties": true } }, "terminations": { "type": "array", "items": { "type": "object", "required": [ "id", "recordType", "title", "source" ], "properties": { "id": { "type": "string" }, "recordType": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object" } }, "additionalProperties": true } }, "cancellations": { "type": "array", "items": { "type": "object", "required": [ "id", "recordType", "title", "source" ], "properties": { "id": { "type": "string" }, "recordType": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object" } }, "additionalProperties": true } } }, "additionalProperties": false }, "normalizedParties": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "support", "sourceSemantics" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "support": { "type": "array", "minItems": 1, "items": { "type": "object" } }, "sourceSemantics": { "type": "object" } }, "additionalProperties": true } }, "provenance": { "type": "array", "items": { "type": "object" } }, "freshness": { "type": "object", "required": [ "schemaVersion", "currentLookupAttempted", "currentLookupVerified", "currentEvidenceUsable", "transportStatus", "parsingStatus", "evidenceStatus", "observation", "fallback" ], "properties": { "schemaVersion": { "const": "filmrightsproof-freshness.v2" }, "currentLookupAttempted": { "type": "boolean" }, "currentLookupVerified": { "type": "boolean", "description": "Narrow compatibility summary. True only when the bounded current lookup completed without normalization rejection; it does not mean exhaustive coverage." }, "currentEvidenceUsable": { "type": "boolean" }, "transportStatus": { "enum": [ "succeeded", "failed", "not_attempted" ] }, "parsingStatus": { "enum": [ "succeeded", "failed", "not_completed", "not_attempted" ] }, "evidenceStatus": { "enum": [ "usable", "usable_no_qualifying_match", "partial", "partial_no_qualifying_match", "zero_hits", "normalization_failed", "unavailable" ] }, "queryStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queryCompletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "observedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "searchScope": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "observation": { "type": "object" }, "fallback": { "type": "object" }, "sourceMix": { "type": "object" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": true }, "coverage": { "type": "object" }, "unresolvedQuestions": { "type": "array", "items": { "type": "string" } }, "nonInferences": { "type": "array", "items": { "type": "string" } }, "evidenceGaps": { "type": "array", "items": { "type": "string" } }, "limitations": { "type": "array", "items": { "type": "string" } }, "methods": { "type": "object" }, "state": { "type": "object" }, "corpusVersion": { "type": "integer" }, "legalNotice": { "type": "string" } }, "additionalProperties": true }, "examples": { "resolved": { "summary": "Resolved dossier with usable current evidence", "value": { "schemaVersion": "trace-public-rights.v1", "operation": "trace_public_rights", "traceId": "trace_example_resolved", "dossierId": "trace_example_resolved", "status": "partial_recorded_lineage", "canonicalRequest": { "title": "Example Film", "creator": "Example Director", "year": 2024, "workType": "film", "limit": 10 }, "resolvedWork": { "title": "Example Film", "registrationNumber": "PA0000000", "matchScore": 100 }, "candidates": [], "records": [], "evidence": { "registrations": [], "renewals": [], "recordations": [], "terminations": [], "cancellations": [] }, "normalizedParties": [], "edges": [], "provenance": [], "freshness": { "schemaVersion": "filmrightsproof-freshness.v2", "currentLookupAttempted": true, "currentLookupVerified": true, "currentEvidenceUsable": true, "transportStatus": "succeeded", "parsingStatus": "succeeded", "evidenceStatus": "usable", "observation": { "returnedCount": 1, "usableRecords": 1, "rejectedRecords": 0, "partial": false }, "fallback": { "used": false } }, "coverage": { "searchCompleteness": "bounded_unknown" }, "unresolvedQuestions": [], "nonInferences": [ "No definitive present ownership is inferred." ], "evidenceGaps": [], "limitations": [ "Public records do not establish private agreements." ], "methods": {}, "state": { "reused": false }, "legalNotice": "Public-record evidence only." } }, "ambiguous": { "summary": "Ambiguous work identity", "value": { "schemaVersion": "trace-public-rights.v1", "operation": "trace_public_rights", "traceId": "trace_example_ambiguous", "dossierId": "trace_example_ambiguous", "status": "ambiguous_work_identity", "canonicalRequest": { "title": "Common Title", "limit": 10 }, "resolvedWork": null, "candidates": [ { "id": "candidate-a", "title": "Common Title", "registrationNumber": "PA-A", "score": 70, "reasons": [ "exact_title" ] }, { "id": "candidate-b", "title": "Common Title", "registrationNumber": "PA-B", "score": 70, "reasons": [ "exact_title" ] } ], "records": [], "evidence": { "registrations": [], "renewals": [], "recordations": [], "terminations": [], "cancellations": [] }, "normalizedParties": [], "edges": [], "provenance": [], "freshness": { "schemaVersion": "filmrightsproof-freshness.v2", "currentLookupAttempted": true, "currentLookupVerified": true, "currentEvidenceUsable": false, "transportStatus": "succeeded", "parsingStatus": "succeeded", "evidenceStatus": "zero_hits", "observation": { "returnedCount": 0, "usableRecords": 0, "rejectedRecords": 0, "partial": false }, "fallback": { "used": false } }, "coverage": { "searchCompleteness": "bounded_unknown" }, "unresolvedQuestions": [ "Which public-record work identity corresponds to the requested property?" ], "nonInferences": [ "No work identity is selected while multiple candidates remain plausible." ], "evidenceGaps": [ "Additional identifying context is required." ], "limitations": [ "A bounded search miss is not evidence that rights do not exist." ], "methods": {}, "state": { "reused": false }, "legalNotice": "Public-record evidence only." } }, "cachedFallback": { "summary": "Cached/historical evidence with current lookup unavailable", "value": { "schemaVersion": "trace-public-rights.v1", "operation": "trace_public_rights", "traceId": "trace_example_cached", "dossierId": "trace_example_cached", "status": "partial_recorded_lineage", "canonicalRequest": { "title": "Example Film", "limit": 10 }, "resolvedWork": { "title": "Example Film", "registrationNumber": "PA0000000" }, "candidates": [], "records": [], "evidence": { "registrations": [], "renewals": [], "recordations": [], "terminations": [], "cancellations": [] }, "normalizedParties": [], "edges": [], "provenance": [], "freshness": { "schemaVersion": "filmrightsproof-freshness.v2", "currentLookupAttempted": true, "currentLookupVerified": false, "currentEvidenceUsable": false, "transportStatus": "failed", "parsingStatus": "not_completed", "evidenceStatus": "unavailable", "observation": { "returnedCount": 0, "usableRecords": 0, "rejectedRecords": 0, "partial": false }, "fallback": { "used": true, "sourcesUsed": [ "bulk", "cached_cprs" ], "bulkCutoff": "2025-06-27" } }, "coverage": { "datasetCutoff": "2025-06-27", "cachedCurrentEvidence": true }, "unresolvedQuestions": [ "Current CPRS state was not independently observed for this request." ], "nonInferences": [ "Cached evidence is not restamped as newly observed." ], "evidenceGaps": [ "Current lookup was unavailable." ], "limitations": [ "Maintained bulk coverage ends 2025-06-27." ], "methods": {}, "state": { "reused": true, "reusedDossier": true }, "legalNotice": "Public-record evidence only." } } } } } }, "402": { "description": "MPP payment challenge when commerce is enabled" } }, "x-filmrightsproof-commerce": { "evaluationMode": false, "commerceAvailable": true, "paymentsRequired": true, "protocol": "MPP", "method": "stripe", "methods": [ "stripe", "tempo" ], "paymentMethods": [ { "id": "stripe", "protocol": "MPP", "method": "stripe", "provider": "stripe", "intents": [ "charge" ] }, { "id": "stripe-mpp-tempo", "protocol": "MPP", "method": "tempo", "provider": "stripe", "asset": "USDC.e", "network": "tempo", "intents": [ "charge" ], "merchantSettlement": "stripe-balance-fiat" } ], "currency": "USD", "freeOperation": "search_public_records", "paidOperation": "trace_public_rights", "tracePriceCents": 200, "stablecoin": { "method": "tempo", "provider": "stripe", "network": "tempo", "asset": "USDC.e", "merchantSettlement": "stripe-balance-fiat" }, "note": "search_public_records remains free; trace_public_rights requires $2.00 USD per completed authorized trace through MPP using Stripe or Tempo stablecoin payment." }, "x-filmrightsproof-price": { "amount": 200, "currency": "USD", "unit": "completed authorized invocation" }, "x-davisville-proof": { "field": "davisvilleProof", "schema": "davisville-proof.v1", "evidenceKernel": "davisville-evidence-kernel.v1", "kernelUrl": "https://davisvillelabs.com/agents/evidence-kernel.json", "primitivesUrl": "https://davisvillelabs.com/agents/evidence-kernel-primitives.v1.json", "schemaUrl": "https://davisvillelabs.com/agents/davisville-proof.v1.schema.json", "conformanceUrl": "https://davisvillelabs.com/agents/evidence-kernel-conformance-v1.json", "trustContractUrl": "https://davisvillelabs.com/agents/trust.json", "manifestUrl": "https://filmrightsproof.com/.well-known/davisville-proof.json", "deliveredOn": [ "filmrightsproof.trace_public_rights", "POST /v1/trace" ], "productResultAuthority": "trace-public-rights.v1 remains the authoritative FilmRightsProof specialist result; davisvilleProof is an additive portable evidence envelope.", "integritySemantics": "The SHA-256 digest detects canonical-content mutation and supports reproducibility. It is not a signature, source authentication, or truth attestation." } } } }, "x-davisville-evidence-kernel": { "field": "davisvilleProof", "schema": "davisville-proof.v1", "evidenceKernel": "davisville-evidence-kernel.v1", "kernelUrl": "https://davisvillelabs.com/agents/evidence-kernel.json", "primitivesUrl": "https://davisvillelabs.com/agents/evidence-kernel-primitives.v1.json", "schemaUrl": "https://davisvillelabs.com/agents/davisville-proof.v1.schema.json", "conformanceUrl": "https://davisvillelabs.com/agents/evidence-kernel-conformance-v1.json", "trustContractUrl": "https://davisvillelabs.com/agents/trust.json", "manifestUrl": "https://filmrightsproof.com/.well-known/davisville-proof.json", "deliveredOn": [ "filmrightsproof.trace_public_rights", "POST /v1/trace" ], "productResultAuthority": "trace-public-rights.v1 remains the authoritative FilmRightsProof specialist result; davisvilleProof is an additive portable evidence envelope.", "integritySemantics": "The SHA-256 digest detects canonical-content mutation and supports reproducibility. It is not a signature, source authentication, or truth attestation." } }