Market 2.0 API

OpenAPI spec of Market 2.0 API.

These APIs can change without any notice as they are still being developed. This page is meant to be a reference for client libraries and SDK to allow parallel development.

List of supported DDO contracts

get

List of supported DDO contracts

Responses

200

Array of contract addresses supported by a system or application.

application/json

contractsstring[]Optional

Contracts represents a list of supported contract addresses in string format.

500

Internal Server Error

application/json

get

/contracts

HTTPcURLJavaScriptPython

GET /contracts HTTP/1.1
Accept: */*

{
  "contracts": [
    "text"
  ]
}

List of supported products

get

List of supported products

Responses

200

Array of products supported by the SP

application/json

productsstring[]Optional

Contracts represents a list of supported contract addresses in string format.

500

Internal Server Error

application/json

get

/products

HTTPcURLJavaScriptPython

GET /products HTTP/1.1
Accept: */*

{
  "products": [
    "text"
  ]
}

List of supported dats sources

get

List of supported data sources

Responses

200

Array of dats sources supported by the SP

application/json

sourcesstring[]Optional

Contracts represents a list of supported contract addresses in string format.

500

Internal Server Error

application/json

get

/sources

HTTPcURLJavaScriptPython

GET /sources HTTP/1.1
Accept: */*

{
  "sources": [
    "text"
  ]
}

List of supported DDO contracts

get

List of supported DDO contracts

Path parameters

idstringRequired

id

Responses

200

the status response for deal products with their respective deal statuses

application/json

400

Bad Request - Invalid input or validation error

application/json

500

Internal Server Error

application/json

get

/status/{id}

HTTPcURLJavaScriptPython

GET /status/{id} HTTP/1.1
Accept: */*

{
  "ddo_v1": {
    "error_msg": "text",
    "status": "accepted"
  },
  "pdp_v1": {
    "error_msg": "text",
    "status": "accepted"
  }
}

Make a mk20 deal

post

Make a mk20 deal

Body

application/json

clientall ofOptional

Client wallet for the deal

objectOptional

identifierinteger[]Optional

Identifier represents a unique identifier for the deal in UUID format.

Responses

200

Ok represents a successful operation with an HTTP status code of 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

ErrDealNotFound indicates that the specified deal could not be found, corresponding to the HTTP status code 404

application/json

422

ErrUnsupportedDataSource indicates the specified data source is not supported or disabled for use in the current context

application/json

423

ErrUnsupportedProduct indicates that the requested product is not supported by the provider

application/json

424

ErrProductNotEnabled indicates that the requested product is not enabled on the provider

application/json

425

ErrProductValidationFailed indicates a failure during product-specific validation due to invalid or missing data

application/json

426

ErrDealRejectedByMarket indicates that a proposed deal was rejected by the market for not meeting its acceptance criteria or rules

application/json

429

ErrServiceOverloaded indicates that the service is overloaded and cannot process the request at the moment

application/json

430

ErrMalformedDataSource indicates that the provided data source is incorrectly formatted or contains invalid data

application/json

440

ErrMarketNotEnabled indicates that the market is not enabled for the requested operation

application/json

441

ErrDurationTooShort indicates that the provided duration value does not meet the minimum required threshold

application/json

500

ErrServerInternalError indicates an internal server error with a corresponding error code of 500

application/json

503

ErrServiceMaintenance indicates that the service is temporarily unavailable due to maintenance, corresponding to HTTP status code 503

application/json

post

/store

HTTPcURLJavaScriptPython

POST /store HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 813

{
  "client": {},
  "data": {
    "format": {
      "aggregate": "[Circular Reference]",
      "car": {},
      "raw": {}
    },
    "piece_cid": {},
    "source_aggregate": {
      "pieces": [
        "[Circular Reference]"
      ]
    },
    "source_http": {
      "urls": [
        {
          "fallback": true,
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": [
              "text"
            ]
          },
          "priority": 1,
          "url": "text"
        }
      ]
    },
    "source_httpput": {},
    "source_offline": {}
  },
  "identifier": [
    1
  ],
  "products": {
    "ddo_v1": {
      "allocation_id": 0,
      "contract_address": "text",
      "contract_verify_method": "text",
      "contract_verify_method_params": [
        1
      ],
      "duration": 1,
      "notification_address": "text",
      "notification_payload": [
        1
      ],
      "piece_manager": {},
      "provider": {}
    },
    "pdp_v1": {
      "add_root": true,
      "create_proof_set": true,
      "delete_proof_set": true,
      "delete_root": true,
      "extra_data": [
        1
      ],
      "proof_set_id": 1,
      "record_keeper": "text",
      "root_ids": [
        1
      ]
    },
    "retrieval_v1": {
      "announce_payload": true,
      "announce_piece": true,
      "indexing": true
    }
  }
}

200

Update the deal details of existing deals.

get

Useful for adding adding additional products and updating PoRep duration

Path parameters

idstringRequired

id

Body

application/json

clientall ofOptional

Client wallet for the deal

objectOptional

identifierinteger[]Optional

Identifier represents a unique identifier for the deal in UUID format.

Responses

200

Ok represents a successful operation with an HTTP status code of 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

ErrDealNotFound indicates that the specified deal could not be found, corresponding to the HTTP status code 404

application/json

422

ErrUnsupportedDataSource indicates the specified data source is not supported or disabled for use in the current context

application/json

423

ErrUnsupportedProduct indicates that the requested product is not supported by the provider

application/json

424

ErrProductNotEnabled indicates that the requested product is not enabled on the provider

application/json

425

ErrProductValidationFailed indicates a failure during product-specific validation due to invalid or missing data

application/json

426

ErrDealRejectedByMarket indicates that a proposed deal was rejected by the market for not meeting its acceptance criteria or rules

application/json

429

ErrServiceOverloaded indicates that the service is overloaded and cannot process the request at the moment

application/json

430

ErrMalformedDataSource indicates that the provided data source is incorrectly formatted or contains invalid data

application/json

440

ErrMarketNotEnabled indicates that the market is not enabled for the requested operation

application/json

441

ErrDurationTooShort indicates that the provided duration value does not meet the minimum required threshold

application/json

500

ErrServerInternalError indicates an internal server error with a corresponding error code of 500

application/json

503

ErrServiceMaintenance indicates that the service is temporarily unavailable due to maintenance, corresponding to HTTP status code 503

application/json

get

/update/{id}

HTTPcURLJavaScriptPython

GET /update/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 813

{
  "client": {},
  "data": {
    "format": {
      "aggregate": "[Circular Reference]",
      "car": {},
      "raw": {}
    },
    "piece_cid": {},
    "source_aggregate": {
      "pieces": [
        "[Circular Reference]"
      ]
    },
    "source_http": {
      "urls": [
        {
          "fallback": true,
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": [
              "text"
            ]
          },
          "priority": 1,
          "url": "text"
        }
      ]
    },
    "source_httpput": {},
    "source_offline": {}
  },
  "identifier": [
    1
  ],
  "products": {
    "ddo_v1": {
      "allocation_id": 0,
      "contract_address": "text",
      "contract_verify_method": "text",
      "contract_verify_method_params": [
        1
      ],
      "duration": 1,
      "notification_address": "text",
      "notification_payload": [
        1
      ],
      "piece_manager": {},
      "provider": {}
    },
    "pdp_v1": {
      "add_root": true,
      "create_proof_set": true,
      "delete_proof_set": true,
      "delete_root": true,
      "extra_data": [
        1
      ],
      "proof_set_id": 1,
      "record_keeper": "text",
      "root_ids": [
        1
      ]
    },
    "retrieval_v1": {
      "announce_payload": true,
      "announce_piece": true,
      "indexing": true
    }
  }
}

200

Finalizes the serial upload process

post

Finalizes the serial upload process once data has been uploaded

Path parameters

idstringRequired

id

Body

application/json

clientall ofOptional

Client wallet for the deal

objectOptional

identifierinteger[]Optional

Identifier represents a unique identifier for the deal in UUID format.

Responses

200

Ok represents a successful operation with an HTTP status code of 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

ErrDealNotFound indicates that the specified deal could not be found, corresponding to the HTTP status code 404

application/json

422

ErrUnsupportedDataSource indicates the specified data source is not supported or disabled for use in the current context

application/json

423

ErrUnsupportedProduct indicates that the requested product is not supported by the provider

application/json

424

ErrProductNotEnabled indicates that the requested product is not enabled on the provider

application/json

425

ErrProductValidationFailed indicates a failure during product-specific validation due to invalid or missing data

application/json

426

ErrDealRejectedByMarket indicates that a proposed deal was rejected by the market for not meeting its acceptance criteria or rules

application/json

429

ErrServiceOverloaded indicates that the service is overloaded and cannot process the request at the moment

application/json

430

ErrMalformedDataSource indicates that the provided data source is incorrectly formatted or contains invalid data

application/json

440

ErrMarketNotEnabled indicates that the market is not enabled for the requested operation

application/json

441

ErrDurationTooShort indicates that the provided duration value does not meet the minimum required threshold

application/json

500

ErrServerInternalError indicates an internal server error with a corresponding error code of 500

application/json

503

ErrServiceMaintenance indicates that the service is temporarily unavailable due to maintenance, corresponding to HTTP status code 503

application/json

post

/upload/{id}

HTTPcURLJavaScriptPython

POST /upload/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 813

{
  "client": {},
  "data": {
    "format": {
      "aggregate": "[Circular Reference]",
      "car": {},
      "raw": {}
    },
    "piece_cid": {},
    "source_aggregate": {
      "pieces": [
        "[Circular Reference]"
      ]
    },
    "source_http": {
      "urls": [
        {
          "fallback": true,
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": [
              "text"
            ]
          },
          "priority": 1,
          "url": "text"
        }
      ]
    },
    "source_httpput": {},
    "source_offline": {}
  },
  "identifier": [
    1
  ],
  "products": {
    "ddo_v1": {
      "allocation_id": 0,
      "contract_address": "text",
      "contract_verify_method": "text",
      "contract_verify_method_params": [
        1
      ],
      "duration": 1,
      "notification_address": "text",
      "notification_payload": [
        1
      ],
      "piece_manager": {},
      "provider": {}
    },
    "pdp_v1": {
      "add_root": true,
      "create_proof_set": true,
      "delete_proof_set": true,
      "delete_root": true,
      "extra_data": [
        1
      ],
      "proof_set_id": 1,
      "record_keeper": "text",
      "root_ids": [
        1
      ]
    },
    "retrieval_v1": {
      "announce_payload": true,
      "announce_piece": true,
      "indexing": true
    }
  }
}

200

Upload the deal data

put

Allows uploading data for deals in a single stream. Suitable for small deals.

Path parameters

idstringRequired

id

Bodyinteger[]

application/json

integer[]Optional

Responses

200

UploadOk indicates a successful upload operation, represented by the HTTP status code 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

UploadStartCodeDealNotFound represents a 404 status indicating the deal was not found during the upload start process

application/json

500

UploadServerError indicates a server-side error occurred during the upload process, represented by the HTTP status code 500

application/json

put

/upload/{id}

HTTPcURLJavaScriptPython

PUT /upload/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 3

[
  1
]

200

Finalizes the upload process

post

Finalizes the upload process once all the chunks are uploaded.

Path parameters

idstringRequired

id

Body

application/json

clientall ofOptional

Client wallet for the deal

objectOptional

identifierinteger[]Optional

Identifier represents a unique identifier for the deal in UUID format.

Responses

200

Ok represents a successful operation with an HTTP status code of 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

ErrDealNotFound indicates that the specified deal could not be found, corresponding to the HTTP status code 404

application/json

422

ErrUnsupportedDataSource indicates the specified data source is not supported or disabled for use in the current context

application/json

423

ErrUnsupportedProduct indicates that the requested product is not supported by the provider

application/json

424

ErrProductNotEnabled indicates that the requested product is not enabled on the provider

application/json

425

ErrProductValidationFailed indicates a failure during product-specific validation due to invalid or missing data

application/json

426

ErrDealRejectedByMarket indicates that a proposed deal was rejected by the market for not meeting its acceptance criteria or rules

application/json

429

ErrServiceOverloaded indicates that the service is overloaded and cannot process the request at the moment

application/json

430

ErrMalformedDataSource indicates that the provided data source is incorrectly formatted or contains invalid data

application/json

440

ErrMarketNotEnabled indicates that the market is not enabled for the requested operation

application/json

441

ErrDurationTooShort indicates that the provided duration value does not meet the minimum required threshold

application/json

500

ErrServerInternalError indicates an internal server error with a corresponding error code of 500

application/json

503

ErrServiceMaintenance indicates that the service is temporarily unavailable due to maintenance, corresponding to HTTP status code 503

application/json

post

/uploads/finalize/{id}

HTTPcURLJavaScriptPython

POST /uploads/finalize/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 813

{
  "client": {},
  "data": {
    "format": {
      "aggregate": "[Circular Reference]",
      "car": {},
      "raw": {}
    },
    "piece_cid": {},
    "source_aggregate": {
      "pieces": [
        "[Circular Reference]"
      ]
    },
    "source_http": {
      "urls": [
        {
          "fallback": true,
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": [
              "text"
            ]
          },
          "priority": 1,
          "url": "text"
        }
      ]
    },
    "source_httpput": {},
    "source_offline": {}
  },
  "identifier": [
    1
  ],
  "products": {
    "ddo_v1": {
      "allocation_id": 0,
      "contract_address": "text",
      "contract_verify_method": "text",
      "contract_verify_method_params": [
        1
      ],
      "duration": 1,
      "notification_address": "text",
      "notification_payload": [
        1
      ],
      "piece_manager": {},
      "provider": {}
    },
    "pdp_v1": {
      "add_root": true,
      "create_proof_set": true,
      "delete_proof_set": true,
      "delete_root": true,
      "extra_data": [
        1
      ],
      "proof_set_id": 1,
      "record_keeper": "text",
      "root_ids": [
        1
      ]
    },
    "retrieval_v1": {
      "announce_payload": true,
      "announce_piece": true,
      "indexing": true
    }
  }
}

200

Status of deal upload

get

Return a json struct detailing the current status of a deal upload.

Path parameters

idstringRequired

id

Responses

200

The status of a file upload process, including progress and missing chunks

application/json

missingintegerOptional

Missing represents the number of chunks that are not yet uploaded.

missing_chunksinteger[]Optional

MissingChunks is a slice containing the indices of missing chunks.

total_chunksintegerOptional

TotalChunks represents the total number of chunks required for the upload.

uploadedintegerOptional

Uploaded represents the number of chunks successfully uploaded.

uploaded_chunksinteger[]Optional

UploadedChunks is a slice containing the indices of successfully uploaded chunks.

400

Bad Request - Invalid input or validation error

application/json

404

UploadStatusCodeDealNotFound indicates that the requested deal was not found, corresponding to status code 404

application/json

425

UploadStatusCodeUploadNotStarted indicates that the upload process has not started yet

application/json

500

UploadStatusCodeServerError indicates an internal server error occurred during the upload process, corresponding to status code 500

application/json

get

/uploads/{id}

HTTPcURLJavaScriptPython

GET /uploads/{id} HTTP/1.1
Accept: */*

{
  "missing": 1,
  "missing_chunks": [
    1
  ],
  "total_chunks": 1,
  "uploaded": 1,
  "uploaded_chunks": [
    1
  ]
}

Starts the upload process

post

Initializes the upload for a deal. Each upload must be initialized before chunks can be uploaded for a deal.

Path parameters

idstringRequired

id

Body

application/json

chunk_sizeintegerOptional

ChunkSize defines the size of each data chunk to be used during the upload process.

raw_sizeintegerOptional

RawSize indicates the total size of the data to be uploaded in bytes.

Responses

200

UploadStartCodeOk indicates a successful upload start request with status code 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

UploadStartCodeDealNotFound represents a 404 status indicating the deal was not found during the upload start process

application/json

409

UploadStartCodeAlreadyStarted indicates that the upload process has already been initiated and cannot be started again

application/json

500

UploadStartCodeServerError indicates an error occurred on the server while processing an upload start request

application/json

post

/uploads/{id}

HTTPcURLJavaScriptPython

POST /uploads/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "chunk_size": 1,
  "raw_size": 1
}

200

Upload a file chunk

put

Allows uploading chunks for a deal file. Method can be called in parallel to speed up uploads.

Path parameters

idstringRequired

id

chunkNumstringRequired

chunkNum

Bodyinteger[]

application/json

integer[]Optional

Responses

200

UploadOk indicates a successful upload operation, represented by the HTTP status code 200

application/json

integer · enumOptionalPossible values:

400

Bad Request - Invalid input or validation error

application/json

404

UploadNotFound represents an error where the requested upload chunk could not be found, typically corresponding to HTTP status 404

application/json

409

UploadChunkAlreadyUploaded indicates that the chunk has already been uploaded and cannot be re-uploaded

application/json

500

UploadServerError indicates a server-side error occurred during the upload process, represented by the HTTP status code 500

application/json

put

/uploads/{id}/{chunkNum}

HTTPcURLJavaScriptPython

PUT /uploads/{id}/{chunkNum} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 3

[
  1
]

200