{"components":{"schemas":{"CollectionsRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/CollectionsRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"orderBy":{"default":"updatedAt","description":"Field to order results by: updatedAt, assetCount, or licensesCount","enum":["updatedAt","assetCount","licensesCount"],"type":"string"},"orderDirection":{"default":"desc","description":"Order direction: asc for least recent, desc for most recent","enum":["asc","desc"],"type":"string"},"pagination":{"$ref":"#/components/schemas/PaginationOptionsHuma","description":"Pagination configuration"},"where":{"$ref":"#/components/schemas/CollectionsWhereOptionsHuma","description":"Optional filter options for collections"}},"type":"object"},"CollectionsResponseBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/CollectionsResponseBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of enriched collections","items":{"$ref":"#/components/schemas/EnrichedCollection"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination metadata"}},"required":["data"],"type":"object"},"CollectionsWhereOptionsHuma":{"additionalProperties":false,"properties":{"collectionAddresses":{"description":"List of collection addresses to filter by (max 200)","items":{"type":"string"},"maxItems":200,"type":["array","null"]},"maxAssetCount":{"description":"Maximum asset count threshold","format":"int64","minimum":0,"type":"integer"},"minAssetCount":{"description":"Minimum asset count threshold","format":"int64","minimum":0,"type":"integer"}},"type":"object"},"ContractMetadata":{"additionalProperties":false,"properties":{"address":{"type":"string"},"chain":{"type":"string"},"contractDeployer":{"type":"string"},"deployedBlockNumber":{"format":"int64","type":"integer"},"name":{"type":"string"},"openSeaMetadata":{"$ref":"#/components/schemas/ContractMetadataOpenSeaMetadataStruct"},"symbol":{"type":"string"},"tokenType":{"type":"string"},"totalSupply":{"type":"string"}},"required":["chain","address","name","symbol","totalSupply","tokenType","contractDeployer","deployedBlockNumber","openSeaMetadata"],"type":"object"},"ContractMetadataByAddressResponse":{"additionalProperties":false,"properties":{"address":{"type":"string"},"chain":{"type":"string"},"contractDeployer":{"type":"string"},"deployedBlockNumber":{"format":"int64","type":"integer"},"name":{"type":"string"},"openSeaMetadata":{"$ref":"#/components/schemas/ContractMetadataByAddressResponseOpenSeaMetadataStruct"},"symbol":{"type":"string"},"tokenType":{"type":"string"},"totalSupply":{"type":"string"}},"required":["chain","address","name","symbol","totalSupply","tokenType","contractDeployer","deployedBlockNumber","openSeaMetadata"],"type":"object"},"ContractMetadataByAddressResponseOpenSeaMetadataStruct":{"additionalProperties":false,"properties":{"bannerImageUrl":{"type":"string"},"collectionName":{"type":"string"},"collectionSlug":{"type":"string"},"description":{"type":"string"},"discordUrl":{"type":"string"},"externalUrl":{"type":["string","null"]},"floorPrice":{"format":"double","type":"number"},"imageUrl":{"type":"string"},"lastIngestedAt":{"format":"date-time","type":"string"},"safelistRequestStatus":{"type":"string"},"twitterUsername":{"type":"string"}},"required":["floorPrice","collectionName","collectionSlug","safelistRequestStatus","imageUrl","description","externalUrl","twitterUsername","discordUrl","bannerImageUrl","lastIngestedAt"],"type":"object"},"ContractMetadataOpenSeaMetadataStruct":{"additionalProperties":false,"properties":{"bannerImageUrl":{"type":"string"},"collectionName":{"type":"string"},"collectionSlug":{"type":"string"},"description":{"type":"string"},"discordUrl":{"type":"string"},"externalUrl":{"type":["string","null"]},"floorPrice":{"format":"double","type":"number"},"imageUrl":{"type":"string"},"lastIngestedAt":{"format":"date-time","type":"string"},"safelistRequestStatus":{"type":"string"},"twitterUsername":{"type":"string"}},"required":["floorPrice","collectionName","collectionSlug","safelistRequestStatus","imageUrl","description","externalUrl","twitterUsername","discordUrl","bannerImageUrl","lastIngestedAt"],"type":"object"},"DerivativeRegisteredEvent":{"additionalProperties":false,"properties":{"blockNumber":{"format":"int64","type":"integer"},"blockTimestamp":{"format":"date-time","type":"string"},"caller":{"type":"string"},"childIpId":{"type":"string"},"id":{"format":"int64","type":"integer"},"licenseTemplate":{"type":"string"},"licenseTermsId":{"type":"string"},"licenseTokenId":{"type":"string"},"logIndex":{"format":"int64","type":"integer"},"parentIpId":{"type":"string"},"processedAt":{"format":"date-time","type":"string"},"txHash":{"type":"string"}},"required":["id","blockNumber","blockTimestamp","txHash","logIndex","caller","childIpId","licenseTokenId","parentIpId","licenseTermsId","licenseTemplate","processedAt"],"type":"object"},"Dispute":{"additionalProperties":false,"properties":{"arbitrationPolicy":{"type":"string"},"blockNumber":{"type":["string","null"]},"blockTimestamp":{"type":"string"},"counterEvidenceHash":{"type":"string"},"currentTag":{"type":"string"},"data":{"type":"string"},"deletedAt":{"type":"string"},"disputeTimestamp":{"type":["string","null"]},"evidenceHash":{"type":"string"},"id":{"type":["string","null"]},"initiator":{"type":"string"},"liveness":{"type":["string","null"]},"logIndex":{"type":"string"},"status":{"type":"string"},"targetIpId":{"type":"string"},"targetTag":{"type":"string"},"transactionHash":{"type":"string"},"umaLink":{"type":"string"}},"required":["id","targetIpId","targetTag","currentTag","arbitrationPolicy","evidenceHash","initiator","data","blockNumber","disputeTimestamp","transactionHash","status","counterEvidenceHash","liveness"],"type":"object"},"DisputePaginationHuma":{"additionalProperties":false,"properties":{"limit":{"default":100,"description":"Number of items to return (max: 200)","examples":[100],"format":"int64","maximum":200,"minimum":1,"type":"integer"},"offset":{"default":0,"description":"Number of items to skip for pagination (v4 enhancement)","examples":[0],"format":"int64","minimum":0,"type":"integer"}},"type":"object"},"DisputePaginationMetadataHuma":{"additionalProperties":false,"properties":{"hasMore":{"description":"Whether there are more disputes","type":"boolean"},"limit":{"description":"Current limit","format":"int64","type":"integer"},"offset":{"description":"Current offset","format":"int64","type":"integer"},"total":{"description":"Total count of disputes","format":"int64","type":"integer"}},"required":["offset","limit","hasMore"],"type":"object"},"DisputeWhereHuma":{"additionalProperties":false,"properties":{"blockNumber":{"description":"Filter by exact block number","examples":["1500000"],"pattern":"^[0-9]+$","type":"string"},"blockNumberGte":{"description":"Filter by block number \u003e= this value (v4 enhancement)","examples":["1000000"],"pattern":"^[0-9]+$","type":"string"},"blockNumberLte":{"description":"Filter by block number \u003c= this value","examples":["2000000"],"pattern":"^[0-9]+$","type":"string"},"id":{"description":"Dispute ID to filter by","examples":["123"],"pattern":"^[0-9]+$","type":"string"},"initiator":{"description":"Initiator wallet address to filter by","examples":["0xabcdef1234567890abcdef1234567890abcdef12"],"pattern":"^0x[a-fA-F0-9]{40}$","type":"string"},"targetIpId":{"description":"Target IP ID to filter by","examples":["0x1234567890abcdef1234567890abcdef12345678"],"pattern":"^0x[a-fA-F0-9]{40}$","type":"string"}},"type":"object"},"DisputesRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/DisputesRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"orderBy":{"description":"Field to order results by (must be blockNumber or empty)","type":"string"},"orderDirection":{"description":"Order direction for results (asc or desc)","type":"string"},"pagination":{"$ref":"#/components/schemas/DisputePaginationHuma","description":"Pagination configuration"},"where":{"$ref":"#/components/schemas/DisputeWhereHuma","description":"Filter options for disputes"}},"type":"object"},"EdgesRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/EdgesRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"orderBy":{"description":"Field to order results by (currently only blockNumber is supported)","enum":["blockNumber"],"type":"string"},"orderDirection":{"default":"desc","description":"Order direction for results","enum":["asc","desc"],"type":"string"},"pagination":{"$ref":"#/components/schemas/PaginationOptionsHuma","description":"Pagination configuration"},"where":{"$ref":"#/components/schemas/EdgesWhereOptionsHuma","description":"Filter options for edges"}},"type":"object"},"EdgesResponseHumaBody":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/EdgesResponseHumaBody.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of derivative registered events (edges)","items":{"$ref":"#/components/schemas/DerivativeRegisteredEvent"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination metadata"}},"required":["data"],"type":"object"},"EdgesWhereOptionsHuma":{"additionalProperties":false,"properties":{"blockNumber":{"description":"Block number to filter by","format":"int64","minimum":0,"type":"integer"},"childIpId":{"description":"Child IP ID to filter by","pattern":"^0x[a-fA-F0-9]{40}$","type":"string"},"parentIpId":{"description":"Parent IP ID to filter by","pattern":"^0x[a-fA-F0-9]{40}$","type":"string"},"txHash":{"description":"Transaction hash to filter by","pattern":"^0x[a-fA-F0-9]{64}$","type":"string"}},"type":"object"},"EnrichedCollection":{"additionalProperties":false,"properties":{"assetCount":{"format":"int64","type":"integer"},"cancelledDisputeCount":{"format":"int64","type":"integer"},"collectionAddress":{"type":"string"},"collectionMetadata":{"$ref":"#/components/schemas/ContractMetadataByAddressResponse"},"createdAt":{"format":"date-time","type":"string"},"judgedDisputeCount":{"format":"int64","type":"integer"},"licensesCount":{"format":"int64","type":"integer"},"raisedDisputeCount":{"format":"int64","type":"integer"},"resolvedDisputeCount":{"format":"int64","type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"required":["collectionAddress","assetCount","licensesCount","resolvedDisputeCount","cancelledDisputeCount","raisedDisputeCount","judgedDisputeCount","updatedAt","createdAt"],"type":"object"},"EnrichedIPAsset":{"additionalProperties":false,"properties":{"ancestorsCount":{"format":"int64","type":"integer"},"blockNumber":{"format":"int64","type":"integer"},"chainId":{"type":"string"},"childrenCount":{"format":"int64","type":"integer"},"createdAt":{"format":"date-time","type":"string"},"descendantsCount":{"format":"int64","type":"integer"},"description":{"type":"string"},"infringementStatus":{"items":{"$ref":"#/components/schemas/InfringementStatus"},"type":["array","null"]},"ipId":{"type":"string"},"ipaMetadataUri":{"type":"string"},"isInGroup":{"type":"boolean"},"lastUpdatedAt":{"format":"date-time","type":"string"},"licenses":{"items":{"$ref":"#/components/schemas/License"},"type":["array","null"]},"logIndex":{"format":"int64","type":"integer"},"moderationStatus":{"$ref":"#/components/schemas/ModerationStatus"},"name":{"type":"string"},"nftMetadata":{"$ref":"#/components/schemas/NFTMetadata"},"ownerAddress":{"type":"string"},"parentsCount":{"format":"int64","type":"integer"},"registrationDate":{"type":"string"},"rootIPs":{"items":{"type":"string"},"type":["array","null"]},"title":{"type":"string"},"tokenContract":{"type":"string"},"tokenId":{"type":"string"},"txHash":{"type":"string"},"uri":{"type":"string"}},"required":["rootIPs","ipId","ownerAddress","blockNumber","logIndex","txHash","chainId","tokenContract","tokenId","name","uri","registrationDate","lastUpdatedAt","createdAt","title","description","parentsCount","ancestorsCount","childrenCount","descendantsCount","isInGroup"],"type":"object"},"ErrorDetail":{"additionalProperties":false,"properties":{"location":{"description":"Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'","type":"string"},"message":{"description":"Error message text","type":"string"},"value":{"description":"The value at the given location"}},"type":"object"},"ErrorModel":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/ErrorModel.json"],"format":"uri","readOnly":true,"type":"string"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","examples":["Property foo is required but is missing."],"type":"string"},"errors":{"description":"Optional list of individual error details","items":{"$ref":"#/components/schemas/ErrorDetail"},"type":["array","null"]},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","examples":["https://example.com/error-log/abc123"],"format":"uri","type":"string"},"status":{"description":"HTTP status code","examples":[400],"format":"int64","type":"integer"},"title":{"description":"A short, human-readable summary of the problem type. This value should not change between occurrences of the error.","examples":["Bad Request"],"type":"string"},"type":{"default":"about:blank","description":"A URI reference to human-readable documentation for the error.","examples":["https://example.com/errors/example"],"format":"uri","type":"string"}},"type":"object"},"GetDisputeResponseHumaBody":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/GetDisputeResponseHumaBody.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"$ref":"#/components/schemas/Dispute","description":"Dispute information"}},"required":["data"],"type":"object"},"IPAssetsRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/IPAssetsRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"includeLicenses":{"description":"Include license information in response","examples":[false],"type":"boolean"},"moderated":{"description":"Filter for moderated content only","examples":[false],"type":"boolean"},"orderBy":{"default":"blockNumber","description":"Field to order results by","enum":["descendantCount","blockNumber","createdAt"],"type":"string"},"orderDirection":{"default":"desc","description":"Order direction for results","enum":["asc","desc"],"type":"string"},"pagination":{"$ref":"#/components/schemas/PaginationOptionsHuma","description":"Pagination configuration"},"where":{"$ref":"#/components/schemas/IPAssetsWhereOptionsHuma","description":"Optional filter options for IP assets"}},"type":"object"},"IPAssetsResponseHumaBody":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/IPAssetsResponseHumaBody.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of enriched IP assets","items":{"$ref":"#/components/schemas/EnrichedIPAsset"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination metadata"}},"required":["data"],"type":"object"},"IPAssetsWhereOptionsHuma":{"additionalProperties":false,"properties":{"ipIds":{"description":"List of IP asset IDs to filter by (max 200)","items":{"type":"string"},"maxItems":200,"type":["array","null"]},"ownerAddress":{"description":"Owner wallet address to filter by","pattern":"^0x[a-fA-F0-9]{40}$","type":"string"},"tokenContract":{"description":"Token contract address to filter by","pattern":"^0x[a-fA-F0-9]{40}$","type":"string"}},"type":"object"},"IPSearchResult":{"additionalProperties":false,"properties":{"description":{"type":"string"},"ipId":{"type":"string"},"mediaType":{"type":"string"},"score":{"format":"double","type":"number"},"similarity":{"format":"double","type":"number"},"title":{"type":"string"}},"required":["ipId","title","description","similarity","score","mediaType"],"type":"object"},"IPTransaction":{"additionalProperties":false,"properties":{"blockNumber":{"format":"int64","type":"integer"},"createdAt":{"format":"date-time","type":"string"},"eventType":{"type":"string"},"id":{"format":"int64","type":"integer"},"initiator":{"type":"string"},"ipId":{"type":"string"},"logIndex":{"format":"int64","type":"integer"},"txHash":{"type":"string"}},"required":["id","txHash","logIndex","blockNumber","eventType","ipId","initiator","createdAt"],"type":"object"},"InfringementStatus":{"additionalProperties":false,"properties":{"createdAt":{"format":"date-time","type":"string"},"customData":{"type":"string"},"infringementDetails":{"type":"string"},"isInfringing":{"type":"boolean"},"providerName":{"type":"string"},"providerURL":{"type":"string"},"responseTime":{"format":"date-time","type":"string"},"status":{"type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["status","isInfringing","providerName","providerURL","infringementDetails","customData","responseTime","createdAt","updatedAt"],"type":"object"},"License":{"additionalProperties":false,"properties":{"createdAt":{"format":"date-time","type":"string"},"licenseTemplateId":{"type":"string"},"licenseTermsId":{"type":"string"},"licensingConfig":{"$ref":"#/components/schemas/LicensingConfig"},"templateMetadataUri":{"type":"string"},"templateName":{"type":"string"},"terms":{"$ref":"#/components/schemas/LicenseTerms"},"updatedAt":{"format":"date-time","type":"string"}},"required":["licenseTemplateId","licenseTermsId","templateName","templateMetadataUri","terms","licensingConfig","createdAt","updatedAt"],"type":"object"},"LicenseTerms":{"additionalProperties":false,"properties":{"commercialAttribution":{"type":"boolean"},"commercialRevCeiling":{"type":"string"},"commercialRevShare":{"format":"int64","type":"integer"},"commercialUse":{"type":"boolean"},"commercializerChecker":{"type":"string"},"commercializerCheckerData":{"type":"string"},"currency":{"type":"string"},"defaultMintingFee":{"type":"string"},"derivativeRevCeiling":{"type":"string"},"derivativesAllowed":{"type":"boolean"},"derivativesApproval":{"type":"boolean"},"derivativesAttribution":{"type":"boolean"},"derivativesReciprocal":{"type":"boolean"},"expiration":{"type":"string"},"royaltyPolicy":{"type":"string"},"transferable":{"type":"boolean"},"uri":{"type":"string"}},"required":["uri","currency","expiration","transferable","commercialUse","royaltyPolicy","defaultMintingFee","commercialRevShare","derivativesAllowed","derivativesApproval","commercialRevCeiling","derivativeRevCeiling","commercialAttribution","commercializerChecker","derivativesReciprocal","derivativesAttribution","commercializerCheckerData"],"type":"object"},"LicenseToken":{"additionalProperties":false,"properties":{"blockNumber":{"type":"string"},"blockTime":{"type":"string"},"burntAt":{"type":"string"},"id":{"type":"string"},"licenseTemplate":{"type":"string"},"licenseTermsId":{"type":"string"},"licensorIpId":{"type":"string"},"owner":{"type":"string"},"transferable":{"type":"string"}},"required":["id","licensorIpId","licenseTemplate","licenseTermsId","transferable","owner","burntAt","blockNumber","blockTime"],"type":"object"},"LicenseTokenPaginationOptionsHuma":{"additionalProperties":false,"properties":{"limit":{"default":100,"description":"Number of items to return","examples":[100],"format":"int64","maximum":200,"minimum":1,"type":"integer"},"offset":{"default":0,"description":"Number of items to skip","examples":[0],"format":"int64","minimum":0,"type":"integer"}},"type":"object"},"LicenseTokensRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/LicenseTokensRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"orderBy":{"default":"blockNumber","description":"Field to order results by (only 'blockNumber' is supported)","enum":["blockNumber"],"type":"string"},"orderDirection":{"default":"desc","description":"Order direction for results ('asc' for ascending, 'desc' for descending)","enum":["asc","desc"],"type":"string"},"pagination":{"$ref":"#/components/schemas/LicenseTokenPaginationOptionsHuma","description":"Pagination configuration (optional, defaults: limit=100, offset=0)"},"where":{"$ref":"#/components/schemas/LicenseTokensWhereOptionsHuma","description":"Optional filter options for license tokens"}},"type":"object"},"LicenseTokensResponseHumaBody":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/LicenseTokensResponseHumaBody.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of license tokens matching the filter criteria","items":{"$ref":"#/components/schemas/LicenseToken"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination metadata including total count and hasMore flag"}},"required":["data"],"type":"object"},"LicenseTokensWhereOptionsHuma":{"additionalProperties":false,"properties":{"licensorIpId":{"description":"Optional licensor IP ID to filter license tokens","examples":["0x0987654321098765432109876543210987654321"],"pattern":"^0x[a-fA-F0-9]{40}$","type":"string"},"ownerAddress":{"description":"Optional owner wallet address to filter license tokens","examples":["0x1234567890123456789012345678901234567890"],"pattern":"^0x[a-fA-F0-9]{40}$","type":"string"}},"type":"object"},"LicensingConfig":{"additionalProperties":false,"properties":{"commercialRevShare":{"format":"int64","type":"integer"},"disabled":{"type":"boolean"},"expectGroupRewardPool":{"type":"string"},"expectMinimumGroupRewardShare":{"format":"int64","type":"integer"},"hookData":{"type":"string"},"isSet":{"type":"boolean"},"licensingHook":{"type":"string"},"mintingFee":{"type":"string"}},"required":["isSet","disabled","hookData","mintingFee","licensingHook","commercialRevShare","expectGroupRewardPool","expectMinimumGroupRewardShare"],"type":"object"},"LineageData":{"additionalProperties":false,"properties":{"edges":{"items":{"$ref":"#/components/schemas/LineageEdge"},"type":["array","null"]},"nodes":{"items":{"$ref":"#/components/schemas/LineageNode"},"type":["array","null"]}},"required":["edges","nodes"],"type":"object"},"LineageEdge":{"additionalProperties":false,"properties":{"blockNumber":{"format":"int64","type":"integer"},"blockTimestamp":{"format":"int64","type":"integer"},"childIpId":{"type":"string"},"direction":{"type":"string"},"id":{"type":"string"},"level":{"format":"int64","type":"integer"},"licenseRoyaltyPolicy":{"type":"string"},"licenseValue":{"type":"string"},"parentIpId":{"type":"string"}},"required":["level","direction","id","blockNumber","blockTimestamp","childIpId","parentIpId","licenseRoyaltyPolicy","licenseValue"],"type":"object"},"LineageMetadata":{"additionalProperties":false,"properties":{"ancestorLevelsReturned":{"format":"int64","type":"integer"},"descendantLevelsReturned":{"format":"int64","type":"integer"},"maxBreadth":{"format":"int64","type":"integer"},"maxDepth":{"format":"int64","type":"integer"},"orderBy":{"type":"string"},"startIpId":{"type":"string"}},"required":["startIpId","maxDepth","maxBreadth","orderBy","ancestorLevelsReturned","descendantLevelsReturned"],"type":"object"},"LineageNode":{"additionalProperties":false,"properties":{"ancestorsCount":{"format":"int64","type":"integer"},"childrenCount":{"format":"int64","type":"integer"},"descendantsCount":{"format":"int64","type":"integer"},"image":{"type":"string"},"ipId":{"type":"string"},"name":{"type":"string"},"parentsCount":{"format":"int64","type":"integer"}},"required":["ipId","name","image","childrenCount","descendantsCount","parentsCount","ancestorsCount"],"type":"object"},"LineageRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/LineageRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"ipId":{"description":"Starting IP asset ID","pattern":"^0x[a-fA-F0-9]{40}$","type":"string"},"maxBreadth":{"default":50,"description":"Max children returned per node at each level","format":"int64","maximum":200,"minimum":1,"type":"integer"},"maxDepth":{"default":2,"description":"Max traversal depth in each direction","format":"int64","maximum":5,"minimum":1,"type":"integer"},"orderBy":{"default":"blockNumber","description":"Field to order children by within each level","enum":["blockNumber","childrenCount","descendantsCount"],"type":"string"},"pagination":{"$ref":"#/components/schemas/PaginationOptionsHuma","description":"Pagination configuration"}},"required":["ipId"],"type":"object"},"LineageResponseHumaBody":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/LineageResponseHumaBody.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"$ref":"#/components/schemas/LineageData","description":"Graph data containing edges and nodes"},"metadata":{"$ref":"#/components/schemas/LineageMetadata","description":"Metadata about the lineage query"},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination metadata"}},"required":["data"],"type":"object"},"ListDisputesResponseHumaBody":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/ListDisputesResponseHumaBody.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of disputes","items":{"$ref":"#/components/schemas/Dispute"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/DisputePaginationMetadataHuma","description":"Pagination metadata (v4 enhancement, not in v3)"}},"required":["data"],"type":"object"},"ModerationStatus":{"additionalProperties":false,"properties":{"adult":{"type":"string"},"medical":{"type":"string"},"racy":{"type":"string"},"spoof":{"type":"string"},"violence":{"type":"string"}},"required":["adult","spoof","medical","violence","racy"],"type":"object"},"NFTMetadata":{"additionalProperties":false,"properties":{"animation":{"$ref":"#/components/schemas/NFTMetadataAnimationStruct"},"collection":{"$ref":"#/components/schemas/NFTMetadataCollectionStruct"},"contract":{"$ref":"#/components/schemas/ContractMetadata"},"contract_address":{"type":"string"},"description":{"type":["string","null"]},"image":{"$ref":"#/components/schemas/NFTMetadataImageStruct"},"mint":{"$ref":"#/components/schemas/NFTMetadataMintStruct"},"name":{"type":"string"},"nft_id":{"type":"string"},"raw":{},"timeLastUpdated":{"format":"date-time","type":"string"},"tokenId":{"type":"string"},"tokenType":{"type":"string"},"tokenUri":{"type":"string"}},"required":["nft_id","contract_address","contract","tokenId","tokenType","name","description","tokenUri","image","animation","raw","collection","mint","timeLastUpdated"],"type":"object"},"NFTMetadataAnimationStruct":{"additionalProperties":false,"properties":{"cachedUrl":{"type":"string"},"contentType":{"type":"string"},"originalUrl":{"type":"string"},"size":{"format":"int64","type":"integer"}},"required":["cachedUrl","contentType","size","originalUrl"],"type":"object"},"NFTMetadataCollectionStruct":{"additionalProperties":false,"properties":{"bannerImageUrl":{"type":"string"},"externalUrl":{"type":["string","null"]},"name":{"type":"string"},"slug":{"type":"string"}},"required":["name","slug","externalUrl","bannerImageUrl"],"type":"object"},"NFTMetadataImageStruct":{"additionalProperties":false,"properties":{"cachedUrl":{"type":"string"},"contentType":{"type":"string"},"originalUrl":{"type":"string"},"pngUrl":{"type":"string"},"size":{"format":"int64","type":"integer"},"thumbnailUrl":{"type":"string"}},"required":["cachedUrl","thumbnailUrl","pngUrl","contentType","size","originalUrl"],"type":"object"},"NFTMetadataMintStruct":{"additionalProperties":false,"properties":{"blockNumber":{"format":"int64","type":["integer","null"]},"mintAddress":{"type":["string","null"]},"timestamp":{"type":["string","null"]},"transactionHash":{"type":["string","null"]}},"required":["mintAddress","blockNumber","timestamp","transactionHash"],"type":"object"},"PaginationMetadataHuma":{"additionalProperties":false,"properties":{"hasMore":{"description":"Whether there are more items","type":"boolean"},"limit":{"description":"Current limit","format":"int64","type":"integer"},"offset":{"description":"Current offset","format":"int64","type":"integer"},"total":{"description":"Total count of items","format":"int64","type":"integer"}},"required":["offset","limit","total","hasMore"],"type":"object"},"PaginationOptionsHuma":{"additionalProperties":false,"properties":{"limit":{"default":20,"description":"Number of items to return","examples":[20],"format":"int64","maximum":200,"minimum":1,"type":"integer"},"offset":{"default":0,"description":"Number of items to skip","examples":[0],"format":"int64","minimum":0,"type":"integer"}},"type":"object"},"SearchRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/SearchRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"mediaType":{"description":"Optional media type filter - must be 'audio', 'video', or 'image'. Leave empty to search all media types","enum":["audio","video","image"],"examples":["image"],"type":"string"},"pagination":{"$ref":"#/components/schemas/PaginationOptionsHuma","description":"Pagination configuration"},"query":{"description":"The search query string","examples":["dragon NFT"],"maxLength":1000,"minLength":1,"type":"string"}},"required":["query"],"type":"object"},"SearchResponseBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/SearchResponseBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of IP asset search results","items":{"$ref":"#/components/schemas/IPSearchResult"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination information"},"total":{"description":"Total number of search results found","format":"int64","type":"integer"}},"required":["data","total"],"type":"object"},"TransactionsRequestBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/TransactionsRequestBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"orderBy":{"default":"blockNumber","description":"Field to order results by","enum":["blockNumber","createdAt","eventType","txHash","ipId","initiator"],"type":"string"},"orderDirection":{"default":"desc","description":"Order direction for results","enum":["asc","desc"],"type":"string"},"pagination":{"$ref":"#/components/schemas/PaginationOptionsHuma","description":"Pagination configuration"},"where":{"$ref":"#/components/schemas/TransactionsWhereOptionsHuma","description":"Optional filter options for transactions"}},"type":"object"},"TransactionsResponseBodyHuma":{"additionalProperties":false,"properties":{"$schema":{"description":"A URL to the JSON Schema for this object.","examples":["https://api.storyapis.com/api/v4/TransactionsResponseBodyHuma.json"],"format":"uri","readOnly":true,"type":"string"},"data":{"description":"List of IP transactions","items":{"$ref":"#/components/schemas/IPTransaction"},"type":["array","null"]},"pagination":{"$ref":"#/components/schemas/PaginationMetadataHuma","description":"Pagination information"}},"required":["data"],"type":"object"},"TransactionsWhereOptionsHuma":{"additionalProperties":false,"properties":{"blockGte":{"description":"Filter transactions from this block number (inclusive)","format":"int64","minimum":0,"type":"integer"},"blockLte":{"description":"Filter transactions up to this block number (inclusive)","format":"int64","minimum":0,"type":"integer"},"eventTypes":{"description":"List of event types to filter by (max 50)","items":{"type":"string"},"maxItems":50,"type":["array","null"]},"initiators":{"description":"List of initiator addresses to filter by (max 200)","items":{"type":"string"},"maxItems":200,"type":["array","null"]},"ipIds":{"description":"List of IP asset IDs to filter by (max 200)","items":{"type":"string"},"maxItems":200,"type":["array","null"]},"txHashes":{"description":"List of transaction hashes to filter by (max 200)","items":{"type":"string"},"maxItems":200,"type":["array","null"]}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"X-Api-Key","type":"apiKey"}}},"info":{"description":"Story Protocol API V4","title":"Story Protocol API V4","version":"v4"},"openapi":"3.1.0","paths":{"/assets":{"post":{"description":"Retrieve a list of IP assets with pagination and filtering options. The 'where' field is optional and should only be provided when filtering by specific IP IDs, owner address, or token contract address. This endpoint can also be used to fetch a single asset by passing its ID in the ipIds filter.","operationId":"listIPAssetsV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPAssetsRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPAssetsResponseHumaBody"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"List IP Assets","tags":["Protocol V4","IP Assets"]}},"/assets/edges":{"post":{"description":"Retrieve a list of edges (derivative registered events) that represent relationships between IP assets. These edges show parent-child relationships formed through licensing.","operationId":"listEdgesV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgesRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgesResponseHumaBody"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"List IP Asset Edges","tags":["Protocol V4","IP Assets"]}},"/assets/lineage":{"post":{"description":"Retrieve the lineage graph (ancestors and descendants) for an IP asset. Returns edges and lightweight node data for graph visualization. Traverses both directions from the starting IP in a single call.","operationId":"listLineageV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineageRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineageResponseHumaBody"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get IP Asset Lineage Graph","tags":["Protocol V4","IP Assets"]}},"/collections":{"post":{"description":"Retrieve a list of collections with pagination and filtering options. Collections can be ordered by updatedAt, assetCount, or licensesCount (asc/desc). Collections are automatically enriched with metadata. The 'where' field is optional and should only be provided when filtering by specific collection addresses or asset counts. This endpoint can also be used to fetch a single collection by passing its address in the collectionAddresses filter. Collections that don't exist in Alchemy or encounter errors will return with empty metadata instead of failing the entire request.","operationId":"listCollectionsV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionsRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionsResponseBodyHuma"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"List Collections","tags":["Protocol V4","Collections"]}},"/disputes":{"post":{"description":"Retrieve a paginated, filtered list of disputes from the SOS database. \nThis endpoint supports various filtering options including:\n- Filter by dispute ID, target IP ID, initiator address, or status\n- Filter by block number ranges (blockNumber, blockNumberLte, blockNumberGte)\n- Sort by block number, dispute timestamp, or ID\n- Pagination with configurable limit and offset\n\nKey v4 Enhancements:\n- Flattened request structure: Query parameters are directly in the request body, not nested in an \"options\" object\n- Offset-based pagination: Unlike v3, this endpoint supports both limit and offset parameters for flexible pagination\n- Block number range filtering: Added blockNumberGte for greater-than-or-equal filtering (complements existing blockNumberLte)\n- Pagination metadata in response: Returns total count and hasMore flag\n\nThe response format is aligned with v3 for compatibility, using big integers for numeric fields and hex strings for data fields.","operationId":"listDisputesV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputesRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDisputesResponseHumaBody"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"List Disputes","tags":["Protocol V4","Disputes"]}},"/disputes/{disputeId}":{"get":{"description":"Retrieve a single dispute by its ID from the SOS database. This endpoint provides detailed information about a specific dispute including its status, involved parties, and related metadata.","operationId":"getDisputeV4","parameters":[{"description":"Dispute ID to retrieve","example":"123","in":"path","name":"disputeId","required":true,"schema":{"description":"Dispute ID to retrieve","examples":["123"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetDisputeResponseHumaBody"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get a Dispute","tags":["Protocol V4","Disputes"]}},"/licenses/tokens":{"post":{"description":"Retrieve license tokens with optional filtering. If no filters are provided, returns all license tokens. Supports filtering by owner wallet address and/or licensor IP ID. Results are paginated and can be ordered by 'blockNumber' (default: descending).","operationId":"getLicenseTokensV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseTokensRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseTokensResponseHumaBody"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get License Tokens","tags":["Protocol V4","License Tokens"]}},"/search":{"post":{"description":"Perform vector search for IP assets based on query text and optional media type filter. This endpoint uses AI-powered search to find relevant assets by semantic similarity.","operationId":"searchV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponseBodyHuma"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Search IP Assets","tags":["Protocol V4","Search"]}},"/transactions":{"post":{"description":"Retrieve a list of IP transactions with pagination and filtering options. The 'where' field is optional and should only be provided when filtering by specific transaction hashes, event types, or block ranges. This endpoint can also be used to fetch specific transactions by passing their hashes in the txHashes filter.","operationId":"listTransactionsV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsRequestBodyHuma"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsResponseBodyHuma"}}},"description":"OK"},"default":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"List IP Transactions","tags":["Protocol V4","Transactions"]}}},"servers":[{"url":"https://api.storyapis.com/api/v4"},{"url":"https://staging-api.storyprotocol.net/api/v4"},{"description":"Local development server","url":"http://localhost:8080/api/v4"}]}