openapi: 3.0.3 info: version: 0.0.1 title: Codex API description: "List of endpoints and interfaces available to Codex API users" security: - { } components: schemas: MultiAddress: type: string description: Address of node as specified by the multi-address specification https://multiformats.io/multiaddr/ example: /ip4/127.0.0.1/tcp/8080 PeerId: type: string description: Peer Identity reference as specified at https://docs.libp2p.io/concepts/fundamentals/peers/ example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N Cid: type: string description: Content Identifier as specified at https://github.com/multiformats/cid example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N SlotId: type: string description: Keccak hash of the abi encoded tuple (RequestId, slot index) example: 268a781e0db3f7cf36b18e5f4fdb7f586ec9edd08e5500b17c0e518a769f114a LogLevel: type: string description: "One of the log levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL" example: DEBUG EthereumAddress: type: string description: Address of Ethereum address Reward: type: string description: The maximum amount of tokens paid per second per slot to hosts the client is willing to pay Duration: type: string description: The duration of the request in seconds as decimal string ProofProbability: type: string description: How often storage proofs are required as decimal string Expiry: type: string description: A timestamp as seconds since unix epoch at which this request expires if the Request does not find requested amount of nodes to host the data. default: 10 minutes ErasureParameters: type: object properties: totalChunks: type: number PoRParameters: description: Parameters for Proof of Retrievability type: object properties: u: type: string publicKey: type: string name: type: string Content: type: object description: Parameters specifying the content properties: cid: $ref: "#/components/schemas/Cid" erasure: $ref: "#/components/schemas/ErasureParameters" por: $ref: "#/components/schemas/PoRParameters" DebugInfo: type: object properties: id: $ref: "#/components/schemas/PeerId" addrs: type: array items: $ref: "#/components/schemas/MultiAddress" repo: type: string description: Path of the data repository where all nodes data are stored spr: type: string description: Signed Peer Record to advertise DHT connection information SalesAvailability: type: object required: - size - minPrice properties: id: type: string description: Hexadecimal identifier of the availability size: type: string description: Size of available storage in bytes as decimal string duration: $ref: "#/components/schemas/Duration" minPrice: type: string description: Minimum price to be paid (in amount of tokens) as decimal string maxCollateral: type: string description: Maximum collateral user is willing to pay per filled Slot (in amount of tokens) as decimal string Slot: type: object properties: id: $ref: "#/components/schemas/SlotId" request: $ref: "#/components/schemas/StorageRequest" slotIndex: type: string description: Slot Index as hexadecimal string StorageRequestCreation: type: object required: - reward - duration - proofProbability - collateral - expiry properties: duration: $ref: "#/components/schemas/Duration" reward: $ref: "#/components/schemas/Reward" proofProbability: $ref: "#/components/schemas/ProofProbability" nodes: type: number description: Minimal number of nodes the content should be stored on default: 1 tolerance: type: number description: Additional number of nodes on top of the `nodes` property that can be lost before pronouncing the content lost default: 0 collateral: type: string description: Number as decimal string that represents how much collateral is asked from hosts that wants to fill a slots expiry: type: string description: Number as decimal string that represents expiry time of the request (in unix timestamp) StorageAsk: type: object required: - reward properties: slots: type: number description: Number of slots (eq. hosts) that the Request want to have the content spread over slotSize: type: string description: Amount of storage per slot (in bytes) as decimal string duration: $ref: "#/components/schemas/Duration" proofProbability: $ref: "#/components/schemas/ProofProbability" reward: $ref: "#/components/schemas/Reward" maxSlotLoss: type: number description: Max slots that can be lost without data considered to be lost StorageRequest: type: object properties: id: type: string description: Request ID client: $ref: "#/components/schemas/EthereumAddress" ask: $ref: "#/components/schemas/StorageAsk" content: $ref: "#/components/schemas/Content" expiry: $ref: "#/components/schemas/Expiry" nonce: type: string description: Random data Purchase: type: object properties: state: type: string description: Description of the Request's state error: type: string description: If Request failed, then here is presented the error message request: $ref: "#/components/schemas/StorageRequest" DataList: type: object properties: content: type: array items: $ref: "#/components/schemas/DataItem" DataItem: type: object properties: cid: $ref: "#/components/schemas/Cid" manifest: $ref: "#/components/schemas/ManifestItem" ManifestItem: type: object properties: rootHash: $ref: "#/components/schemas/Cid" description: "Root hash of the content" originalBytes: type: number description: "Length of original content in bytes" blockSize: type: number description: "Size of blocks" protected: type: boolean description: "Indicates if content is protected by erasure-coding" Space: type: object properties: totalBlocks: type: number description: "Number of blocks stored by the node" quotaMaxBytes: type: number description: "Maximum storage space used by the node" quotaUsedBytes: type: number description: "Amount of storage space currently in use" quotaReservedBytes: type: number description: "Amount of storage space reserved" servers: - url: "http://localhost:8080/api/codex/v1" tags: - name: Marketplace description: Marketplace information and operations - name: Data description: Data operations - name: Node description: Node management - name: Debug description: Debugging configuration paths: "/connect/{peerId}": get: summary: "Connect to a peer" description: | If `addrs` param is supplied, it will be used to dial the peer, otherwise the `peerId` is used to invoke peer discovery, if it succeeds the returned addresses will be used to dial. tags: [ Node ] operationId: connectPeer parameters: - in: path name: peerId required: true schema: $ref: "#/components/schemas/PeerId" description: Peer that should be dialed. - in: query name: addrs schema: type: array nullable: true items: $ref: "#/components/schemas/MultiAddress" description: | If supplied, it will be used to dial the peer. The address has to target the listening address of the peer, which is specified with the `--listen-addrs` CLI flag. responses: "200": description: Successfully connected to peer "400": description: Peer either not found or was not possible to dial "/data": get: summary: "Lists manifest CIDs stored locally in node." tags: [ Data ] operationId: listData responses: "200": description: Retrieved list of content CIDs content: application/json: schema: type: array items: $ref: "#/components/schemas/DataList" "400": description: Invalid CID is specified "404": description: Content specified by the CID is not found "500": description: Well it was bad-bad post: summary: "Upload a file in a streaming manner. Once finished, the file is stored in the node and can be retrieved by any node in the network using the returned CID." tags: [ Data ] operationId: upload requestBody: content: application/octet-stream: schema: type: string format: binary responses: "200": description: CID of uploaded file content: text/plain: schema: type: string "500": description: Well it was bad-bad and the upload did not work out "/data/{cid}": get: summary: "Download a file from the local node in a streaming manner. If the file is not available locally, a 404 is returned." tags: [ Data ] operationId: downloadLocal parameters: - in: path name: cid required: true schema: $ref: "#/components/schemas/Cid" description: File to be downloaded. responses: "200": description: Retrieved content specified by CID content: application/octet-stream: schema: type: string format: binary "400": description: Invalid CID is specified "404": description: Content specified by the CID is unavailable locally "500": description: Well it was bad-bad "/data/{cid}/network": get: summary: "Download a file from the network in a streaming manner. If the file is not available locally, it will be retrieved from other nodes in the network if able." tags: [ Data ] operationId: downloadNetwork parameters: - in: path name: cid required: true schema: $ref: "#/components/schemas/Cid" description: "File to be downloaded." responses: "200": description: Retrieved content specified by CID content: application/octet-stream: schema: type: string format: binary "400": description: Invalid CID is specified "404": description: Content specified by the CID is not found "500": description: Well it was bad-bad "/space": get: summary: "Gets a summary of the storage space allocation of the node." tags: [ Data ] operationId: space responses: "200": description: "Summary of storage allocation" content: application/json: schema: $ref: "#/components/schemas/Space" "500": description: "It's not working as planned" "/sales/slots": get: summary: "Returns active slots" tags: [ Marketplace ] operationId: getActiveSlots responses: "200": description: Retrieved active slots content: application/json: schema: type: array items: $ref: "#/components/schemas/Slot" "503": description: Sales are unavailable "/sales/slots/{slotId}": get: summary: "Returns active slot with id {slotId} for the host" tags: [ Marketplace ] operationId: getActiveSlotById parameters: - in: path name: slotId required: true schema: $ref: "#/components/schemas/Cid" description: File to be downloaded. responses: "200": description: Retrieved active slot content: application/json: schema: $ref: "#/components/schemas/Slot" "400": description: Invalid or missing SlotId "404": description: Host is not in an active sale for the slot "503": description: Sales are unavailable "/sales/availability": get: summary: "Returns storage that is for sale" tags: [ Marketplace ] operationId: getOfferedStorage responses: "200": description: Retrieved storage availabilities of the node content: application/json: schema: type: array items: $ref: "#/components/schemas/SalesAvailability" "500": description: Error getting unused availabilities "503": description: Sales are unavailable post: summary: "Offers storage for sale" operationId: offerStorage tags: [ Marketplace ] requestBody: content: application/json: schema: $ref: "#/components/schemas/SalesAvailability" responses: "200": description: Created storage availability content: application/json: schema: $ref: "#/components/schemas/SalesAvailability" "500": description: Error reserving availablility "503": description: Sales are unavailable "/storage/request/{cid}": post: summary: "Creates a new Request for storage" tags: [ Marketplace ] operationId: createStorageRequest parameters: - in: path name: cid required: true schema: $ref: "#/components/schemas/Cid" description: CID of the uploaded data that should be stored requestBody: content: application/json: schema: $ref: "#/components/schemas/StorageRequestCreation" responses: "200": description: Returns the Request ID as decimal string "400": description: Invalid or missing Request ID "404": description: Request ID not found "503": description: Purchasing is unavailable "/storage/purchases": get: summary: "Returns list of purchase IDs" tags: [ Marketplace ] operationId: getPurchases responses: "200": description: Gets all purchase IDs stored in node content: application/json: schema: type: array items: type: string "503": description: Purchasing is unavailable "/storage/purchases/{id}": get: summary: "Returns purchase details" tags: [ Marketplace ] operationId: getPurchase parameters: - in: path name: id required: true schema: type: string description: Hexadecimal ID of a Purchase responses: "200": description: Purchase details content: application/json: schema: $ref: "#/components/schemas/Purchase" "400": description: Invalid or missing Purchase ID "404": description: Purchase not found "503": description: Purchasing is unavailable "/debug/chronicles/loglevel": post: summary: "Set log level at run time" tags: [ Debug ] operationId: setDebugLogLevel parameters: - in: query name: level required: true schema: $ref: "#/components/schemas/LogLevel" responses: "200": description: Successfully log level set "400": description: Invalid or missing log level "500": description: Well it was bad-bad "/debug/info": get: summary: "Gets node information" operationId: getDebugInfo tags: [ Debug ] responses: "200": description: Node's information content: application/json: schema: $ref: "#/components/schemas/DebugInfo"