CIDgravity logo
API docs by Redocly

CIDgravity Public API (1.0.0)

CIDgravity team: contact@cidgravity.com License: BSD-2-Clause-Patent Terms of Service

You can download this OpenAPI specification on https://service.cidgravity.com/docs/openapi-public.json

General Usage

This document details use of CIDgravity's REST API. Our REST API is organised into publicly accessible endpoints (version, status, etc.), and private authenticated endpoints (on chain deals, user data, etc.) which require requests to be authenticated.

Support

If you have trouble making any standard requests that our system permits, please join our Slack community and send us a message, so that we may investigate further.

Requests, Responses and Errors

Requests

Request payloads are JSON encoded (Content-Type: application/json)

Responses

Responses are JSON encoded and contain one or two top-level keys (result and error for successful requests or those with warnings, or only error for failed or rejected requests)

Example Successful Response

{
    "error": null,
    "result": {
        "version": "v5.2.10"
    }
}

With cursor based pagination

The next parameter will be returned as a cursor on the last element returned in the current page and can be used to select the following elements

{
    "error": null,
    "next": 2,
    "result": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ]
}

GET https://service.cidgravity.com/public/v1/get-version

Example Rejection

{
    "error": {
        "code": "d2907321-ae78-4209-a0de-a22f15d3f2e6",
        "message": "resource could not be found"
    }
}

Errors

HTTP status codes

HTTP status codes are generally used by our API to convey information about the state of requests Status codes other than 200 indicate that there was an issue with processing the request.

In addition to the status code, the error returned contains a message field with more details

Some Common Examples

Status code Additional Info
400 - Bad request The request payload is malformed, incorrect or ambiguous
401 - Unauthorized This request need an authentication using X-API-KEY as HTTP header
403 - Forbidden You don't have access to the requested ressource
404 - Not found Ressource not found
429 - Too many requests Rate limits are reached (See Rate limit section)
500 - Server error The server can't process your request at this time

All HTTP status code are available on this link

CIDgravity status codes

All CIDgravity status codes are available on this link

Authentication

Authenticated requests must include X-API-KEY HTTP header.

Headers and Signature

All errors responses will include the code value in the body. This uniquely identifies your request. When contacting support, please include this value where possible.

API-Key

The "X-API-KEY" header should contain your API key. This information can be found on CIDgravity application under Settings menu.

Security Scheme Type: API Key Header parameter name: X-API-KEY

Rate Limits

At this time, our REST API endpoints doesn't have any rate limits.

Note: Our REST API is currently under active development, and the rate limits may change in the future

Changelog

  • Dec 2023 - Added initial version of CIDgravity API

Tooling

Get Filecoin epochs duration from days

Convert a duration in days to a duration in Filecoin epochs.

Request Body schema: application/json
required
duration
integer <int64>

duration in days

Responses

Response Schema: application/json
error
object
result
integer <int64>

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/public/v1/get-filecoin-epoch-duration-from-days \
  --header 'content-type: application/json' \
  --data '{"duration":180}'

Response samples

Content type
application/json
{
  • "error": { },
  • "result": 518400
}

Get Filecoin epoch from unix timestamp

Convert a unix timestamp to a Filecoin epoch.

Request Body schema: application/json
required
unixTimestamp
integer <int64>

unix timestamp in milliseconds

Responses

Response Schema: application/json
error
object
result
integer <int64>

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/public/v1/get-filecoin-epoch-from-unix-timestamp \
  --header 'content-type: application/json' \
  --data '{"unixTimestamp":1710836620000}'

Response samples

Content type
application/json
{
  • "error": { },
  • "result": 3751007
}

Reporting

Get on chain deals

Retrieve all client on chain deals, paginated with 10 000 items per page.

Eligible plans: Clients (free plan), Clients (premium plan)

Authorizations:
ApiKeyAuth
Request Body schema: application/json
sortBy
string
Enum: "dealId" "lastUpdate"

column to sort results by. Default value to dealId if not provided

next
string

cursor to get the next elements. Default to null to get first page

Responses

Response Schema: application/json
error
object
next
string

the cursor to retrieve the next elements. If no results are found, a null value is returned.

object
object
lastUpdate
number

date of last status update (unix timestamp)

object
PieceSize
integer <int64>

piece size in bytes

object
VerifiedDeal
boolean
Client
string
Provider
string
Label
string
StartEpoch
integer <int64>

deal start epoch in Filecoin epoch

EndEpoch
integer <int64>

deal end epoch in Filecoin epoch

StoragePricePerEpoch
string

deal price in attoFIL / GiB / Epoch

ProviderCollateral
string

provider collateral in attoFIL

ClientCollateral
string

client collateral in attoFil

object
status
string
Enum: "published" "published-expired" "active" "slashed" "expired" "unknown"

current status of the deal on the chain

publishedEpoch
integer <int64>

epoch at which the deal was published on chain (-1 if not available)

onChainStartEpoch
integer <int64>

epoch when the deal started (-1 if not available)

onChainEndEpoch
integer <int64>

epoch when the deal started (-1 if not available)

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/private/v1/get-on-chain-deals \
  --header 'X-API-KEY: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"sortBy":"dealId","next":"string"}'

Response samples

Content type
application/json
{
  • "error": { },
  • "next": "66859071",
  • "result": {
    • "66859070": {
      • "lastUpdate": 1706859612.4239538,
      • "proposal": {
        • "PieceSize": 34359738368,
        • "PieceCID": {
          • "/": "baga6ea4seaqfyiicys4rxe6pncl3np4g4eeavhh5qrq2lvqluhufkdk5iuvgyli"
          },
        • "VerifiedDeal": true,
        • "Client": "f01859221",
        • "Provider": "f010479",
        • "Label": "bafkqaaa",
        • "StartEpoch": 3590631,
        • "EndEpoch": 5105511,
        • "StoragePricePerEpoch": "0",
        • "ProviderCollateral": "0",
        • "ClientCollateral": "0"
        },
      • "state": {
        • "status": "active",
        • "publishedEpoch": 3195382,
        • "onChainStartEpoch": 3196696,
        • "onChainEndEpoch": -1
        }
      }
    }
}

Booking SP

Get best available providers

Return 3 providers immediatly available to accept specific deal proposal

Eligible plans: Clients (free plan), Clients (premium plan)

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
pieceCid
string
startEpochHeadOffset
integer <int64>

start epoch by when the deal should be proved by provider on-chain after current chain head in Filecoin epochs. This parameter is not allowed to be used with startEpoch (default value: 5760 epochs = 2 days)

startEpoch
integer <int64>

start epoch by when the deal should be proved by provider in Filecoin epochs. This parameter is not allowed to be used with startEpochHeadOffset

duration
required
integer <int64>

deal duration in Filecoin epoch

storagePricePerEpoch
required
string

deal price in attoFIL / GiB / Epoch

providerCollateral
string

provider collateral in attoFIL. Will be calculated from the chain if not specified.

verifiedDeal
required
boolean
transferSize
required
integer <int64>

car size in Bytes

transferType
required
string
Enum: "http" "graphsync" "libp2p" "manual"
removeUnsealedCopy
required
boolean

Responses

Response Schema: application/json
error
object
object
reason
string
Enum: "ONBOARDING_IN_PROGRESS" "ONBOARDING_COMPLETED" "NO_PROVIDERS_AVAILABLE"

reason provided only if the providers list is empty

providers
Array of strings

array of 3 providers (miner id)

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/private/v1/get-best-available-providers \
  --header 'X-API-KEY: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"pieceCid":"baga6ea4seaqfyiicys4rxe6pncl3np4g4eeavhh5qrq2lvqluhufkdk5iuvgyli","startEpochHeadOffset":5760,"startEpoch":3590631,"duration":515400,"storagePricePerEpoch":"0","providerCollateral":"0","verifiedDeal":true,"transferSize":34359738368,"transferType":"http","removeUnsealedCopy":false}'

Response samples

Content type
application/json
{
  • "error": { },
  • "result": {
    • "reason": "ONBOARDING_IN_PROGRESS",
    • "providers": [
      • "string"
      ]
    }
}

Get provider availability

Check if specific provider is available to accept specific deal proposal

Eligible plans: Clients (free plan), Clients (premium plan)

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
pieceCid
string
startEpochHeadOffset
integer <int64>

start epoch by when the deal should be proved by provider on-chain after current chain head in Filecoin epochs. This parameter is not allowed to be used with startEpoch (default value: 5760 epochs = 2 days)

startEpoch
integer <int64>

start epoch by when the deal should be proved by provider in Filecoin epochs. This parameter is not allowed to be used with startEpochHeadOffset

providerAddressId
required
string
duration
required
integer <int64>

deal duration in Filecoin epoch

storagePricePerEpoch
required
string

deal price in attoFIL / GiB / Epoch

providerCollateral
string

provider collateral in attoFIL. Will be calculated from the chain if not specified.

verifiedDeal
required
boolean
transferSize
required
integer <int64>

car size in Bytes

transferType
required
string
Enum: "http" "graphsync" "libp2p" "manual"
removeUnsealedCopy
required
boolean

Responses

Response Schema: application/json
error
object
object
reason
string

CIDgravity status code only if isAvailable = false

message
string

Quick status code description only if reason

isAvailable
boolean

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/private/v1/get-provider-availability \
  --header 'X-API-KEY: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"pieceCid":"baga6ea4seaqfyiicys4rxe6pncl3np4g4eeavhh5qrq2lvqluhufkdk5iuvgyli","startEpochHeadOffset":5760,"startEpoch":3590631,"providerAddressId":"f010479","duration":1514880,"storagePricePerEpoch":"0","providerCollateral":"0","verifiedDeal":true,"transferSize":34359738368,"transferType":"http","removeUnsealedCopy":false}'

Response samples

Content type
application/json
{
  • "error": { },
  • "result": {
    • "reason": "string",
    • "message": "string",
    • "isAvailable": true
    }
}

Export onboarding poliy

Generate a JSON with the entire onboarding policy configuration and all groups. Same format must be used for importation

Eligible plans: Clients (premium plan)

Authorizations:
ApiKeyAuth

Responses

Response Schema: application/json
error
object
object
object
priority
string
Enum: "policy_respected" "number_of_copies"
object
numberOfCopies
integer <int64>

number of copies in mix group

Array of objects
Array
name
string

name of the group

Array of objects

list of providers

numberOfCopies
integer <int64>

number of copies expected in this group

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/private/v1/onboarding-policy/export \
  --header 'X-API-KEY: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "error": { },
  • "result": {
    • "settings": {
      • "priority": "policy_respected"
      },
    • "mixGroup": {
      • "numberOfCopies": 4
      },
    • "groups": [
      • {
        • "name": "Group name",
        • "providers": [
          • {
            • "addressId": "f010479",
            • "comment": "Twin Quasar"
            }
          ],
        • "numberOfCopies": 1
        }
      ]
    }
}

Import onboarding policy

Import entire onboarding policy including settings and groups for current tenant

Eligible plans: Clients (premium plan)

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
object
priority
string
Enum: "policy_respected" "number_of_copies"
object
numberOfCopies
integer <int64>

number of copies in mix group

Array of objects
Array
name
string

name of the group

Array of objects

list of providers

Array
addressId
string

provider short address

comment
string
numberOfCopies
integer <int64>

number of copies expected in this group

Responses

Request samples 

curl --request POST \
  --url https://service.cidgravity.com/private/v1/onboarding-policy/import \
  --header 'X-API-KEY: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"settings":{"priority":"policy_respected"},"mixGroup":{"numberOfCopies":4},"groups":[{"name":"Group name","providers":[{"addressId":"f010479","comment":"Twin Quasar"}],"numberOfCopies":1}]}'

Response samples

Content type
application/json
{
  • "error": {
    • "code": "string",
    • "message": "PROVIDER_BLACKLISTED"
    }
}