{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "CIDgravity Public API",
    "description" : "You can download this OpenAPI specification on [https://service.cidgravity.com/docs/openapi-public.json](https://service.cidgravity.com/docs/openapi-public.json)\n\n# General Usage\nThis document details use of CIDgravity's REST API. \nOur REST API is organised into publicly accessible endpoints (version, status, etc.), and\nprivate authenticated endpoints (on chain deals, user data, etc.) which require requests to be authenticated.\n\n# Support\nIf you have trouble making any standard requests that our system permits, please \n[join our Slack community](https://filecoinproject.slack.com/archives/C04SCAG37FH) and send us a message, \nso that we may investigate further.\n\n# Requests, Responses and Errors\n## Requests\nRequest payloads are JSON encoded (`Content-Type: application/json`)\n\n## Responses\nResponses are JSON encoded and contain one or two top-level keys (`result` and `error` for successful \nrequests or those with warnings, or only `error` for failed or rejected requests)\n\n### Example Successful Response\n\n```\n{\n    \"error\": null,\n    \"result\": {\n        \"version\": \"v5.2.10\"\n    }\n}\n```\n\n#### With cursor based pagination\nThe `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\n\n```\n{\n    \"error\": null,\n    \"next\": 2,\n    \"result\": [\n        {\n            \"id\": 1\n        },\n        {\n            \"id\": 2\n        }\n    ]\n}\n```\n\n> GET [https://service.cidgravity.com/public/v1/get-version](https://service.cidgravity.com/public/v1/get-version)\n\n### Example Rejection\n\n```\n{\n    \"error\": {\n        \"code\": \"d2907321-ae78-4209-a0de-a22f15d3f2e6\",\n        \"message\": \"resource could not be found\"\n    }\n}\n```\n\n## Errors\n### HTTP status codes\nHTTP status codes are generally used by our API to convey information about the state of requests \nStatus codes **other** than 200 indicate that there was an issue with processing the request.\n\nIn addition to the status code, the error returned contains a `message` field with more details\n\n#### Some Common Examples\n| Status code | Additional Info |\n| -- | -- |\n| 400 - Bad request | The request payload is malformed, incorrect or ambiguous |\n| 401 - Unauthorized | This request need an authentication using X-API-KEY as HTTP header |\n| 403 - Forbidden |  You don't have access to the requested ressource |\n| 404 - Not found | Ressource not found |\n| 429 - Too many requests | Rate limits are reached (See `Rate limit` section) |\n| 500 - Server error | The server can't process your request at this time |\n\nAll HTTP status code [are available on this link](https://developer.mozilla.org/fr/docs/Web/HTTP/Status)\n\n### CIDgravity status codes\nAll CIDgravity status codes [are available on this link](https://docs.cidgravity.com/reference/client-error-codes)\n\n# Authentication\nAuthenticated requests must include `X-API-KEY` HTTP header. \n\n## Headers and Signature\nAll errors responses will include the `code` value in the body. \nThis uniquely identifies your request. When contacting support, please include this value where possible.\n\n## API-Key\nThe \"X-API-KEY\" header should contain your API key.\nThis information can be found on CIDgravity application under Settings menu.\n\n**Security Scheme Type:** API Key\n**Header parameter name:** `X-API-KEY`\n\n# Rate Limits\nAt this time, our REST API endpoints doesn't have any rate limits.\n\n> **Note:** Our REST API is currently under active development, and the rate limits may change in the future\n\n# Changelog\n* Dec 2023 - Added initial version of CIDgravity API",
    "termsOfService" : "https://www.cidgravity.com/terms/",
    "contact" : {
      "name" : "CIDgravity team",
      "email" : "contact@cidgravity.com"
    },
    "license" : {
      "name" : "BSD-2-Clause-Patent",
      "url" : "https://spdx.org/licenses/BSD-2-Clause-Patent.html"
    },
    "version" : "1.0.0",
    "x-logo" : {
      "url" : "https://app.cidgravity.com/images/CIDgravity-Logo-Transparent.png",
      "backgroundColor" : "#343741",
      "altText" : "CIDgravity logo"
    }
  },
  "servers" : [ {
    "url" : "https://service.cidgravity.com"
  } ],
  "paths" : {
    "/private/v1/get-on-chain-deals" : {
      "post" : {
        "tags" : [ "Reporting" ],
        "summary" : "Get on chain deals",
        "description" : "Retrieve all client on chain deals, paginated with 10 000 items per page.\n\n**Eligible plans:** Clients (free plan), Clients (premium plan)",
        "operationId" : "getOnChainDealsV1",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "sortBy" : {
                    "$ref" : "#/components/schemas/ValidSortByValue"
                  },
                  "next" : {
                    "type" : "string",
                    "description" : "cursor to get the next elements. Default to null to get first page"
                  }
                }
              }
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : "List of deals retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ValidResponseSchema"
                }
              }
            }
          }
        },
        "security" : [ {
          "ApiKeyAuth" : [ ]
        } ]
      }
    },
    "/private/v1/get-best-available-providers" : {
      "post" : {
        "tags" : [ "Booking SP" ],
        "summary" : "Get best available providers",
        "description" : "Return 3 providers immediatly available to accept specific deal proposal\n\n**Eligible plans:** Clients (free plan), Clients (premium plan)",
        "operationId" : "getBestAvailableProvidersV1",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "required" : [ "startEpoch", "duration", "storagePricePerEpoch", "verifiedDeal", "transferSize", "transferType", "removeUnsealedCopy", "providerCollateral" ],
                "type" : "object",
                "properties" : {
                  "pieceCid" : {
                    "type" : "string",
                    "example" : "baga6ea4seaqfyiicys4rxe6pncl3np4g4eeavhh5qrq2lvqluhufkdk5iuvgyli"
                  },
                  "startEpoch" : {
                    "type" : "integer",
                    "description" : "deal start epoch in Filecoin epoch",
                    "format" : "int64",
                    "example" : 3590631
                  },
                  "duration" : {
                    "type" : "integer",
                    "description" : "deal duration in Filecoin epoch",
                    "format" : "int64",
                    "example" : 515400
                  },
                  "storagePricePerEpoch" : {
                    "type" : "string",
                    "description" : "deal price in attoFIL / GiB / Epoch",
                    "example" : "0"
                  },
                  "providerCollateral" : {
                    "type" : "string",
                    "description" : "provider collateral in attoFIL",
                    "example" : "0"
                  },
                  "verifiedDeal" : {
                    "type" : "boolean"
                  },
                  "transferSize" : {
                    "type" : "integer",
                    "description" : "car size in Bytes",
                    "format" : "int64",
                    "example" : 34359738368
                  },
                  "transferType" : {
                    "$ref" : "#/components/schemas/ValidTransferType"
                  },
                  "removeUnsealedCopy" : {
                    "type" : "boolean",
                    "example" : false
                  }
                }
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Providers retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "error" : {
                      "type" : "object"
                    },
                    "result" : {
                      "type" : "object",
                      "properties" : {
                        "reason" : {
                          "$ref" : "#/components/schemas/ValidDiscoveryReason"
                        },
                        "providers" : {
                          "type" : "array",
                          "description" : "array of 3 providers (miner id)",
                          "items" : {
                            "type" : "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security" : [ {
          "ApiKeyAuth" : [ ]
        } ]
      }
    },
    "/private/v1/get-provider-availability" : {
      "post" : {
        "tags" : [ "Booking SP" ],
        "summary" : "Get provider availability",
        "description" : "Check if specific provider is available to accept specific deal proposal\n\n**Eligible plans:** Clients (free plan), Clients (premium plan)",
        "operationId" : "getProviderAvailabilityV1",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "required" : [ "provider", "startEpoch", "duration", "storagePricePerEpoch", "verifiedDeal", "transferSize", "transferType", "removeUnsealedCopy", "providerCollateral" ],
                "type" : "object",
                "properties" : {
                  "pieceCid" : {
                    "type" : "string",
                    "example" : "baga6ea4seaqfyiicys4rxe6pncl3np4g4eeavhh5qrq2lvqluhufkdk5iuvgyli"
                  },
                  "provider" : {
                    "type" : "string",
                    "example" : "f010479"
                  },
                  "startEpoch" : {
                    "type" : "integer",
                    "description" : "deal start epoch in Filecoin epoch",
                    "format" : "int64",
                    "example" : 3590631
                  },
                  "duration" : {
                    "type" : "integer",
                    "description" : "deal duration in Filecoin epoch",
                    "format" : "int64",
                    "example" : 1514880
                  },
                  "storagePricePerEpoch" : {
                    "type" : "string",
                    "description" : "deal price in attoFIL / GiB / Epoch",
                    "example" : "0"
                  },
                  "providerCollateral" : {
                    "type" : "string",
                    "description" : "provider collateral in attoFIL",
                    "example" : "0"
                  },
                  "verifiedDeal" : {
                    "type" : "boolean"
                  },
                  "transferSize" : {
                    "type" : "integer",
                    "description" : "car size in Bytes",
                    "format" : "int64",
                    "example" : 34359738368
                  },
                  "transferType" : {
                    "$ref" : "#/components/schemas/ValidTransferType"
                  },
                  "removeUnsealedCopy" : {
                    "type" : "boolean",
                    "example" : false
                  }
                }
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Availability retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "error" : {
                      "type" : "object"
                    },
                    "result" : {
                      "type" : "object",
                      "properties" : {
                        "reason" : {
                          "type" : "string",
                          "description" : "CIDgravity status code only if isAvailable = false"
                        },
                        "message" : {
                          "type" : "string",
                          "description" : "Quick status code description only if reason"
                        },
                        "isAvailable" : {
                          "type" : "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security" : [ {
          "ApiKeyAuth" : [ ]
        } ]
      }
    },
    "/public/v1/get-filecoin-epoch-duration-from-days" : {
      "post" : {
        "tags" : [ "Tooling" ],
        "summary" : "Get Filecoin epochs duration from days",
        "description" : "Convert a duration in days to a duration in Filecoin epochs.",
        "operationId" : "getFilecoinEpochDurationFromDays",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "duration" : {
                    "type" : "integer",
                    "description" : "duration in days",
                    "format" : "int64",
                    "example" : 180
                  }
                }
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Value converted",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "error" : {
                      "type" : "object"
                    },
                    "result" : {
                      "type" : "integer",
                      "format" : "int64",
                      "example" : 518400
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/public/v1/get-filecoin-epoch-from-unix-timestamp" : {
      "post" : {
        "tags" : [ "Tooling" ],
        "summary" : "Get Filecoin epoch from unix timestamp",
        "description" : "Convert a unix timestamp to a Filecoin epoch.",
        "operationId" : "getFilecoinEpochFromUnixTimestamp",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "unixTimestamp" : {
                    "type" : "integer",
                    "description" : "unix timestamp in milliseconds",
                    "format" : "int64",
                    "example" : 1710836620000
                  }
                }
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Value converted",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "error" : {
                      "type" : "object"
                    },
                    "result" : {
                      "type" : "integer",
                      "format" : "int64",
                      "example" : 3751007
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/private/v1/onboarding-policy/export" : {
      "post" : {
        "tags" : [ "Booking SP" ],
        "summary" : "Export onboarding poliy",
        "description" : "Generate a JSON with the entire onboarding policy configuration and all groups. Same format must be used for importation\n\n**Eligible plans:** Clients (premium plan)",
        "operationId" : "exportOnboardingPolicy",
        "responses" : {
          "200" : {
            "description" : "Data retrieved",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "error" : {
                      "type" : "object"
                    },
                    "result" : {
                      "$ref" : "#/components/schemas/OnboardingPolicyImportExport"
                    }
                  }
                }
              }
            }
          }
        },
        "security" : [ {
          "ApiKeyAuth" : [ ]
        } ]
      }
    },
    "/private/v1/onboarding-policy/import" : {
      "post" : {
        "tags" : [ "Booking SP" ],
        "summary" : "Import onboarding policy",
        "description" : "Import entire onboarding policy including settings and groups for current tenant\n\n**Eligible plans:** Clients (premium plan)",
        "operationId" : "importOnboardingPolicy",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/OnboardingPolicyImportExport"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "Imported"
          },
          "400" : {
            "description" : "Bad request",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponseSchema"
                }
              }
            }
          }
        },
        "security" : [ {
          "ApiKeyAuth" : [ ]
        } ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "ValidSortByValue" : {
        "type" : "string",
        "description" : "column to sort results by. Default value to dealId if not provided",
        "enum" : [ "dealId", "lastUpdate" ]
      },
      "ValidResponseSchema" : {
        "type" : "object",
        "properties" : {
          "error" : {
            "type" : "object"
          },
          "next" : {
            "type" : "string",
            "description" : "the cursor to retrieve the next elements. If no results are found, a null value is returned.",
            "example" : "66859071"
          },
          "result" : {
            "type" : "object",
            "properties" : {
              "66859070" : {
                "type" : "object",
                "properties" : {
                  "lastUpdate" : {
                    "type" : "number",
                    "description" : "date of last status update (unix timestamp)",
                    "example" : 1706859612.4239538
                  },
                  "proposal" : {
                    "$ref" : "#/components/schemas/Proposal"
                  },
                  "state" : {
                    "type" : "object",
                    "properties" : {
                      "status" : {
                        "$ref" : "#/components/schemas/ValidOnChainStatus"
                      },
                      "publishedEpoch" : {
                        "type" : "integer",
                        "description" : "epoch at which the deal was published on chain (-1 if not available)",
                        "format" : "int64",
                        "example" : 3195382
                      },
                      "onChainStartEpoch" : {
                        "type" : "integer",
                        "description" : "epoch when the deal started (-1 if not available)",
                        "format" : "int64",
                        "example" : 3196696
                      },
                      "onChainEndEpoch" : {
                        "type" : "integer",
                        "description" : "epoch when the deal started (-1 if not available)",
                        "format" : "int64",
                        "example" : -1
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Proposal" : {
        "type" : "object",
        "properties" : {
          "PieceSize" : {
            "type" : "integer",
            "description" : "piece size in bytes",
            "format" : "int64",
            "example" : 34359738368
          },
          "PieceCID" : {
            "$ref" : "#/components/schemas/Cid"
          },
          "VerifiedDeal" : {
            "type" : "boolean",
            "example" : true
          },
          "Client" : {
            "type" : "string",
            "example" : "f01859221"
          },
          "Provider" : {
            "type" : "string",
            "example" : "f010479"
          },
          "Label" : {
            "type" : "string",
            "example" : "bafkqaaa"
          },
          "StartEpoch" : {
            "type" : "integer",
            "description" : "deal start epoch in Filecoin epoch",
            "format" : "int64",
            "example" : 3590631
          },
          "EndEpoch" : {
            "type" : "integer",
            "description" : "deal end epoch in Filecoin epoch",
            "format" : "int64",
            "example" : 5105511
          },
          "StoragePricePerEpoch" : {
            "type" : "string",
            "description" : "deal price in attoFIL / GiB / Epoch",
            "example" : "0"
          },
          "ProviderCollateral" : {
            "type" : "string",
            "description" : "provider collateral in attoFIL",
            "example" : "0"
          },
          "ClientCollateral" : {
            "type" : "string",
            "description" : "client collateral in attoFil",
            "example" : "0"
          }
        }
      },
      "Cid" : {
        "type" : "object",
        "properties" : {
          "/" : {
            "type" : "string",
            "example" : "baga6ea4seaqfyiicys4rxe6pncl3np4g4eeavhh5qrq2lvqluhufkdk5iuvgyli"
          }
        }
      },
      "ValidOnChainStatus" : {
        "type" : "string",
        "description" : "current status of the deal on the chain",
        "example" : "active",
        "enum" : [ "published", "published-expired", "active", "slashed", "expired", "unknown" ]
      },
      "ValidTransferType" : {
        "type" : "string",
        "enum" : [ "http", "graphsync", "libp2p", "manual" ]
      },
      "ValidDiscoveryReason" : {
        "type" : "string",
        "description" : "reason provided only if the providers list is empty",
        "enum" : [ "ONBOARDING_IN_PROGRESS", "ONBOARDING_COMPLETED", "NO_PROVIDERS_AVAILABLE" ]
      },
      "OnboardingPolicyImportExport" : {
        "type" : "object",
        "properties" : {
          "settings" : {
            "$ref" : "#/components/schemas/OnboardingPolicyImportExportSettings"
          },
          "mixGroup" : {
            "$ref" : "#/components/schemas/OnboardingPolicyImportExportMixGroup"
          },
          "groups" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/OnboardingPolicyImportExportGroup"
            }
          }
        }
      },
      "OnboardingPolicyImportExportSettings" : {
        "type" : "object",
        "properties" : {
          "priority" : {
            "$ref" : "#/components/schemas/onboardingPolicyPriority"
          }
        }
      },
      "onboardingPolicyPriority" : {
        "type" : "string",
        "enum" : [ "policy_respected", "number_of_copies" ]
      },
      "OnboardingPolicyImportExportMixGroup" : {
        "type" : "object",
        "properties" : {
          "numberOfCopies" : {
            "type" : "integer",
            "description" : "number of copies in mix group",
            "format" : "int64",
            "example" : 4
          }
        }
      },
      "OnboardingPolicyImportExportGroup" : {
        "type" : "object",
        "properties" : {
          "name" : {
            "type" : "string",
            "description" : "name of the group",
            "example" : "Group name"
          },
          "providers" : {
            "type" : "array",
            "description" : "list of providers",
            "items" : {
              "$ref" : "#/components/schemas/OnboardingPolicyImportExportProvider"
            }
          },
          "numberOfCopies" : {
            "type" : "integer",
            "description" : "number of copies expected in this group",
            "format" : "int64",
            "example" : 1
          }
        }
      },
      "OnboardingPolicyImportExportProvider" : {
        "type" : "object",
        "properties" : {
          "addressId" : {
            "type" : "string",
            "description" : "provider short address",
            "example" : "f010479"
          },
          "comment" : {
            "type" : "string",
            "example" : "Twin Quasar"
          }
        }
      },
      "ErrorResponseSchema" : {
        "type" : "object",
        "properties" : {
          "error" : {
            "type" : "object",
            "properties" : {
              "code" : {
                "type" : "string"
              },
              "message" : {
                "oneOf" : [ {
                  "$ref" : "#/components/schemas/ImportValidationErrorCodes"
                }, {
                  "type" : "string"
                } ]
              }
            }
          }
        }
      },
      "ImportValidationErrorCodes" : {
        "type" : "string",
        "description" : "Returned error code specifying the validation rule that failed",
        "enum" : [ "PROVIDER_BLACKLISTED", "NUMBER_OF_GROUP_LIMIT_EXCEEDED", "GROUP_MUST_CONTAINS_AT_LEAST_ONE_PROVIDER", "GROUP_NAME_MUST_BE_UNIQUE", "PROVIDER_DUPLICATED_IN_OTHER_GROUP", "NUMBER_OF_COPIES_GREATER_THAN_PROVIDERS", "GROUP_NAME_ALREADY_USED", "PROVIDER_ALREADY_USED", "INVALID_PROVIDER_ADDRESS", "NOT_SHORT_ADDRESS", "NOT_FOUND_ON_CHAIN", "GROUP_NAME_CONTAINS_RESERVED_WORD_MIX" ]
      }
    },
    "securitySchemes" : {
      "ApiKeyAuth" : {
        "type" : "apiKey",
        "name" : "X-API-KEY",
        "in" : "header"
      }
    }
  },
  "x-tagGroups" : [ {
    "name" : "Public Endpoints",
    "tags" : [ "Chain info", "Stats", "Tooling" ]
  }, {
    "name" : "Authenticated Enpoints",
    "tags" : [ "Reporting", "Booking SP" ]
  } ]
}