List Disputes

curl --request POST \
  --url https://api.storyapis.com/api/v4/disputes \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "orderBy": "<string>",
  "orderDirection": "<string>",
  "pagination": {
    "limit": 100,
    "offset": 0
  },
  "where": {
    "blockNumber": "<string>",
    "blockNumberGte": "<string>",
    "blockNumberLte": "<string>",
    "id": "<string>",
    "initiator": "<string>",
    "targetIpId": "<string>"
  }
}
'

{
  "data": [
    {
      "arbitrationPolicy": "<string>",
      "blockNumber": "<string>",
      "counterEvidenceHash": "<string>",
      "currentTag": "<string>",
      "data": "<string>",
      "disputeTimestamp": "<string>",
      "evidenceHash": "<string>",
      "id": "<string>",
      "initiator": "<string>",
      "liveness": "<string>",
      "status": "<string>",
      "targetIpId": "<string>",
      "targetTag": "<string>",
      "transactionHash": "<string>",
      "blockTimestamp": "<string>",
      "deletedAt": "<string>",
      "logIndex": "<string>",
      "umaLink": "<string>"
    }
  ],
  "$schema": "<string>",
  "pagination": {
    "hasMore": true,
    "limit": 123,
    "offset": 123,
    "total": 123
  }
}

Endpoints

List Disputes

Retrieve a paginated, filtered list of disputes from the SOS database. This endpoint supports various filtering options including:

Filter by dispute ID, target IP ID, initiator address, or status
Filter by block number ranges (blockNumber, blockNumberLte, blockNumberGte)
Sort by block number, dispute timestamp, or ID
Pagination with configurable limit and offset

Key v4 Enhancements:

Flattened request structure: Query parameters are directly in the request body, not nested in an “options” object
Offset-based pagination: Unlike v3, this endpoint supports both limit and offset parameters for flexible pagination
Block number range filtering: Added blockNumberGte for greater-than-or-equal filtering (complements existing blockNumberLte)
Pagination metadata in response: Returns total count and hasMore flag

The response format is aligned with v3 for compatibility, using big integers for numeric fields and hex strings for data fields.

POST

disputes

List Disputes

curl --request POST \
  --url https://api.storyapis.com/api/v4/disputes \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "orderBy": "<string>",
  "orderDirection": "<string>",
  "pagination": {
    "limit": 100,
    "offset": 0
  },
  "where": {
    "blockNumber": "<string>",
    "blockNumberGte": "<string>",
    "blockNumberLte": "<string>",
    "id": "<string>",
    "initiator": "<string>",
    "targetIpId": "<string>"
  }
}
'

{
  "data": [
    {
      "arbitrationPolicy": "<string>",
      "blockNumber": "<string>",
      "counterEvidenceHash": "<string>",
      "currentTag": "<string>",
      "data": "<string>",
      "disputeTimestamp": "<string>",
      "evidenceHash": "<string>",
      "id": "<string>",
      "initiator": "<string>",
      "liveness": "<string>",
      "status": "<string>",
      "targetIpId": "<string>",
      "targetTag": "<string>",
      "transactionHash": "<string>",
      "blockTimestamp": "<string>",
      "deletedAt": "<string>",
      "logIndex": "<string>",
      "umaLink": "<string>"
    }
  ],
  "$schema": "<string>",
  "pagination": {
    "hasMore": true,
    "limit": 123,
    "offset": 123,
    "total": 123
  }
}

Authorizations

X-Api-Key

string

header

required

Body

application/json

orderBy

string

Field to order results by (must be blockNumber or empty)

orderDirection

string

Order direction for results (asc or desc)

pagination

object

Pagination configuration

Show child attributes

where

object

Filter options for disputes

Show child attributes

Response

data

object[] | null

required

List of disputes

Show child attributes

$schema

string<uri>

read-only

A URL to the JSON Schema for this object.

Example:

"https://api.storyapis.com/api/v4/ListDisputesResponseHumaBody.json"

pagination

object

Pagination metadata (v4 enhancement, not in v3)

Show child attributes

List Collections Get a Dispute

⌘I