Storage API

In all cURL examples, parameters with a colon as a prefix should be replaced with real values.

File upload process through Apillon Web3 Storage API

  1. Request signed URL(s) for upload.
  2. File is uploaded to Apillon central server.
  3. File is transferred to IPFS and available through the Apillon gateway.
  4. File is replicated to different IPFS nodes globally via Crust Network.

List buckets

API to list all buckets in project. Items are paginated and can be filtered and ordered through query parameters. This is a listing request.

GET /storage/buckets

Query parameters

All query parameters from listing request plus:

NameDescriptionRequired
bucketTypeType of bucket: 1(storage bucket), 2(website bucket) and 3(nft bucket).false

Response fields (bucket)

Each item is an instance of the bucket model with the below properties:

FieldTypeDescription
createTimeDateTimeItem create time
updateTimeDateTimeItem last update time
bucketUuidstringBucket unique identifier
bucketTypeintegerItem type with possible values 1(storage bucket), 2(website bucket) and 3(nft bucket)
namestringBucket name
descriptionstringBucket description
sizeintegerSize of bucket in bytes

curl --location --request GET "https://api.apillon.io/storage/buckets" \
--header "Authorization: Basic :credentials"
curl --location --request GET "https://api.apillon.io/storage/buckets?search=My bucket" \
--header "Authorization: Basic :credentials"
{
    "id": "75095bf9-e976-45c8-8a9d-e013ca3b203a",
    "status": 200,
    "data": {
        "items": [
            ...
            {
                "createTime": "2022-12-06T12:03:32.000Z",
                "updateTime": "2023-10-09T11:42:23.000Z",
                "bucketUuid": "cee9f151-a371-495b-acd2-4362fbb87780",
                "bucketType": 1,
                "name": "Storage bucket",
                "description": "",
                "size": 3215839730
            }
            ...
        ],
        "total": 10
    }
}

Create new bucket

API for creating a new storage bucket. NFT and website buckets are automatically generated when a new website or NFT collection is initialized.

POST /storage/buckets

Body fields

NameTypeDescriptionRequired
namestringBucket name.true
descriptionstringBucket description.false

Possible errors

CodeDescription
42200003Request body is missing a name field.

Response

A response is an instance of bucket, described above.


curl --location --request POST "https://api.apillon.io/storage/buckets" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{ \"name\": \"My bucket\" }"
{
  "id": "e50c8276-fd8d-47c4-b42a-bf19645a204b",
  "status": 201,
  "data": {
    "createTime": "2023-10-12T11:49:49.551Z",
    "updateTime": "2023-10-12T11:49:49.551Z",
    "bucketUuid": "8218080f-1321-4687-9a89-200b06afb930",
    "bucketType": 1,
    "name": "My bucket",
    "description": null,
    "size": 0
  }
}

Upload to bucket

API that creates file upload requests and returns URLs for file upload along with sessionUuid.

POST /storage/buckets/:bucketUuid/upload

URL parameters

NameDescriptionRequired
bucketUuidUnique key of storage bucket. Key is displayed on developer dashboard.true

Body fields

NameTypeDescriptionRequired
filesarrayArray of files metadata. Maximum 200 items.true
sessionUuidstringSession unique key, which must be specified to add more uploads to existing session.false

Each metadata object in the files array contains the properties below.

NameTypeDescriptionRequired
fileNamestringFull name (name and extension) of file to be uploadedtrue
contentTypestringFile MIME typeopen in new windowfalse
pathstringVirtual file path. Empty for root. It must not contain fileName.

The path field can be used to place file in virtual directories inside a bucket. If directories do not yet exist, they will be automatically generated.

For example, an images/icons path creates an images directory in a bucket and an icons directory inside it. A file will then be created in the icons directory.
false

Possible errors

CodeDescription
40406002Bucket does not exist.
40406009Bucket is marked for deletion. It is no longer possible to upload files to it.
40006020HTML files cannot be uploaded to storage bucket in freemium subscription plan.
42200040Request body is missing a files field.
42200150files has invalid length. It should be between 1 and 200
42200008Request body file object is missing a fileName field.
50006003Internal error - Apillon was unable to generate upload URL.

Response

NameTypeDescription
sessionUuidstringSession unique key, which is later used to end upload and transfer files to bucket
filesarrayArray of files metadata.

Files in the request body are returned in response data.files property. Each file is equipped with url and fileUuid. All properties are displayed below.

FieldTypeDescription
urlstringURL for file upload. Signed URL is unique for each file and is valid only for a limited time (1 min), so you should start with file upload as soon as possible.

Request should use PUT method and binary body.

Binary data should be sent in body as-is, but with the appropriate Content-Type header (e.g., text/plain).
fileUuidstringFile unique identifier used to query file status, etc.
fileNamestringFull name (name and extension) of file to be uploaded
contentTypestringFile MIME typeopen in new window
pathstringFile path on the storage bucket.

curl --location --request POST "https://api.apillon.io/storage/buckets/:bucketUuid/upload" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"files\": [
        {
            \"fileName\": \"My test file\",
            \"contentType\": \"text/html\"
        }
    ]

}"
{
  "id": "cbdc4930-2bbd-4b20-84fa-15daa4429952",
  "status": 201,
  "data": {
    "sessionUuid": "3b6113bc-f265-4662-8cc5-ea86f06cc74b",
    "files": [
      {
        "path": null,
        "fileName": "My test file",
        "contentType": "text/html",
        "url": "https://sync-to-ipfs-queue.s3.eu-west-1.amazonaws.com/STORAGE_sessions/73/3b6113bc-f265-4662-8cc5-ea86f06cc74b/My%20test%20file?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQIMRRA6GJRL57L7G%2F20230215%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230215T114524Z&X-Amz-Expires=900&X-Amz-Signature=499367f6c6bff5be50686724475ac2fa6307b77b94fd1a25584c092fe74b0a58&X-Amz-SignedHeaders=host&x-id=PutObject",
        "fileUuid": "4ef1177b-f7c9-4434-be56-a559cec0cc18"
      }
    ]
  }
}

Example for uploading to signed URL:

curl --location --request PUT "https://sync-to-ipfs-queue.s3.eu-west-1.amazonaws.com/STORAGE_sessions/73/3b6113bc-f265-4662-8cc5-ea86f06cc74b/My%20test%20file?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQIMRRA6GJRL57L7G%2F20230215%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230215T114524Z&X-Amz-Expires=900&X-Amz-Signature=499367f6c6bff5be50686724475ac2fa6307b77b94fd1a25584c092fe74b0a58&X-Amz-SignedHeaders=host&x-id=PutObject" \
--data-binary "My test content"
curl --location --request PUT "https://sync-to-ipfs-queue.s3.eu-west-1.amazonaws.com/STORAGE_sessions/73/3b6113bc-f265-4662-8cc5-ea86f06cc74b/My%20test%20file?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQIMRRA6GJRL57L7G%2F20230215%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230215T114524Z&X-Amz-Expires=900&X-Amz-Signature=499367f6c6bff5be50686724475ac2fa6307b77b94fd1a25584c092fe74b0a58&X-Amz-SignedHeaders=host&x-id=PutObject" \
--header "Content-Type: text/plain" \
--data-binary ":full path to file"

End upload session

Once files are uploaded to the cloud server via the received URL, trigger file sync to IPFS and CRUST.

Note: Files in session can be wrapped to CID on IPFS via the wrapWithDirectory body field. This means that the directory gets its own CID and its content cannot be modified afterwards. The directory path is mandatory when the wrapWithDirectory option is set to true. Read more about this option in the IPFS docsopen in new window

POST /storage/buckets/:bucketUuid/upload/:sessionUuid/end

URL parameters

NameDescriptionRequired
bucketUuidUnique key of bucket. Key is displayed in developer dashboard.true
sessionUuidSession uuid, recieved in upload to buckettrue

Body fields

NameTypeDescriptionRequired
wrapWithDirectorybooleanWrap uploaded files to IPFS directoryfalse
directoryPathstringPath to wrapped directory inside bucketfalse

Possible errors

CodeDescription
40406004Session does not exist
40006001Files in this session were already transferred

Response

API responds with the status 200 OK if operation is successfully executed.


curl --location --request POST "https://api.apillon.io/storage/buckets/:bucketUuid/upload/:sessionUuid/end" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
{
  "id": "b64b1c07-1a8a-4b05-9e3b-3c6a519d6ff7",
  "status": 200,
  "data": true
}

List bucket content

Lists bucket directories and files in a folder structure. Endpoint lists files and directories in a single directory; if directoryUuid is not present, endpoint lists items in the bucket root directory. More about listing requests can be found here

Note: This endpoint returns files from ended sessions. I.e. files with fileStatus 2, 3 or 4.

GET /storage/buckets/:bucketUuid/content

URL parameters

NameDescriptionRequired
bucketUuidUnique key of bucket. Key is displayed on developer dashboard.true

Query parameters

All query parameters from listing request plus:

NameDescriptionRequired
directoryUuidGets items inside a specific directory.false
markedForDeletionInclude deleted bucketsfalse

Possible errors

CodeDescription
40406002Bucket does not exist.

Response fields

Properties of each item:

FieldTypeDescription
uuidstringItem UUID property
typeintegerItem type with possible values 1(directory) and 2(file)
namestringItem (directory or file) name
CIDstringFile content identifier - label used to point to content in IPFS.
createTimeDateTimeItem create time
updateTimeDateTimeItem last update time
contentTypestringItem content type (MIME type).
sizeintegerItem size in bytes
directoryUuidstringUuid of directory where the file directory is located
linkstringLink on IPFS gateway.
fileStatusnumberCurrent status of file

curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/content" \
--header "Authorization: Basic :credentials"
curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/content?orderBy=name&desc=false&limit=5&page=1" \
--header "Authorization: Basic :credentials"
{
    "id": "c8c50b3b-91ff-42c7-b0af-f866ce23f18a",
    "status": 200,
    "data": {
        "items": [
            ...
            {
                "uuid": "d61753fd-26ba-45cb-9277-89e96d6cfd11",
                "type": 1,
                "name": "Folder 1",
                "CID": null,
                "createTime": "2023-10-12T12:20:54.000Z",
                "updateTime": "2023-10-12T12:20:54.000Z",
                "contentType": null,
                "size": null,
                "directoryUuid": null,
                "link": null,
                "fileStatus": null
            },
            {
                "uuid": "63ace39b-ec7c-4889-8d94-83a2ad7fb154",
                "type": 2,
                "name": "My file.txt",
                "CID": "QmaufbAR2dX62TSiYYJUS5sV9KNFZLnxgP4ZMkKFoJhSAM",
                "createTime": "2023-10-12T12:17:19.000Z",
                "updateTime": "2023-10-12T12:17:42.000Z",
                "contentType": "",
                "size": 6,
                "directoryUuid": null,
                "link": "https://ipfs-dev.apillon.io/ipfs/QmaufbAR2dX62TSiYYJUS5sV9KNFZLnxgP4ZMkKFoJhSAM",
                "fileStatus": 3
            }
            ...
        ],
        "total": 10
    }
}

List files

Lists files inside a bucket. This endpoint returns all files in a flat structure and each file has a path property. More about listing requests can be found here

Note: This endpoint returns files from ended sessions. I.e. files with fileStatus 2, 3 or 4.

GET /storage/buckets/:bucketUuid/files

URL parameters

NameDescriptionRequired
bucketUuidUnique key of bucket. Key is displayed on developer dashboard.true

Possible errors

CodeDescription
40406002Bucket does not exist.

Response fields

Properties of each item:

FieldTypeDescription
createTimeDateTimeFile create time
updateTimeDateTimeFile last update time
fileUuidstringFile UUID property
CIDstringFile content identifier - label used to point to content in IPFS.
namestringFile name
contentTypestringFile content type. Value is taken from file upload request
pathintegerFull path to file
sizeintegerFile size in bytes
fileStatusnumberFile statuses are described in below table
linkstringLink on IPFS gateway.

curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/files" \
--header "Authorization: Basic :credentials"
curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/files?search=Hello.txt" \
--header "Authorization: Basic :credentials"
{
    "id": "c8c50b3b-91ff-42c7-b0af-f866ce23f18a",
    "status": 200,
    "data": {
        "items": [
            ...
            {
                "createTime": "2023-10-12T12:20:54.000Z",
                "updateTime": "2023-10-13T06:08:00.000Z",
                "fileUuid": "120afe0e-b146-45a5-82e0-52d2125df294",
                "CID": "QmXKvPVY6jJ7e4oL3QcYjKFw6Bg7EKzzJAXCgXYjuCSyq5",
                "name": "Hello.txt",
                "contentType": "",
                "path": "Folder 1/",
                "size": 11,
                "fileStatus": 3,
                "link": "https://ipfs-dev.apillon.io/ipfs/QmXKvPVY6jJ7e4oL3QcYjKFw6Bg7EKzzJAXCgXYjuCSyq5"
            },
            {
                "createTime": "2023-10-12T12:17:19.000Z",
                "updateTime": "2023-10-12T12:17:42.000Z",
                "fileUuid": "63ace39b-ec7c-4889-8d94-83a2ad7fb154",
                "CID": "QmaufbAR2dX62TSiYYJUS5sV9KNFZLnxgP4ZMkKFoJhSAM",
                "name": "My file.txt",
                "contentType": "",
                "path": null,
                "size": 6,
                "fileStatus": 3,
                "link": "https://ipfs-dev.apillon.io/ipfs/QmaufbAR2dX62TSiYYJUS5sV9KNFZLnxgP4ZMkKFoJhSAM"
            }
            ...
        ],
        "total": 10
    }
}

Get file details

Gets details of a specific file inside a bucket.

GET /storage/buckets/:bucketUuid/files/:fileUuid

URL parameters

NameDescriptionrequired
bucketUuidUnique key of a bucket. Key is displayed on developer dashboard.true
fileUuidFile UUID or CID.true

Possible errors

CodeDescription
40406005File does not exist.

Response fields

FieldTypeDescription
createTimeDateTimeFile create time
updateTimeDateTimeFile last update time
fileUuidstringFile UUID property
CIDstringFile content identifier - label used to point to content in IPFS.
namestringFile name
contentTypestringFile content type. Value is taken from file upload request
pathintegerFull path to file
sizeintegerFile size in bytes
fileStatusnumberFile statuses are described in below table
directoryUuidstringUuid of directory where the file is located
linkstringLink on IPFS gateway.
File statuses
NumberDescription
1Request for upload to Apillon storage was generated.
2File is uploaded to Apillon central server.
3File is transferred to the IPFS node.
4File is replicated to different IPFS nodes through Crust Network.

curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/files/:fileUuid" \
--header "Authorization: Basic :credentials"
{
  "id": "1beec975-9836-48b2-a284-591ae01f7a58",
  "status": 200,
  "data": {
    "createTime": "2023-10-12T12:20:54.000Z",
    "updateTime": "2023-10-12T12:21:17.000Z",
    "fileUuid": "120afe0e-b146-45a5-82e0-52d2125df294",
    "CID": "bafybeiefrfkhkevhdvacfjds7gw7mh2wlnuo66aeyffrik7wao5tlvfy3q",
    "name": "Hello.txt",
    "contentType": "",
    "path": "Folder 1/",
    "size": 11,
    "fileStatus": 3,
    "link": "https://ipfs-dev.apillon.io/ipfs/QmXKvPVY6jJ7e4oL3QcYjKFw6Bg7EKzzJAXCgXYjuCSyq5",
    "directoryUuid": "d61753fd-26ba-45cb-9277-89e96d6cfd11"
  }
}

Delete file

Marks a file inside a bucket for deletion. The file will be completely deleted from the Apillon system and Apillon IPFS node after three (3) months. If a file is marked for deletion, it will not be renewed on Crust Network.

DELETE /storage/buckets/:bucketUuid/files/:fileUuid

URL parameters

NameDescriptionrequired
bucketUuidUnique key of bucket. Key is displayed on developer dashboard.true
fileUuidFile unique identifier.true

Possible errors

CodeDescription
40406005File does not exist.
40006009File is already marked for deletion.

Response fields

The response of the delete function is a boolean value, depends on whether the deletion was successful.


curl --location --request DELETE "https://api.apillon.io/storage/buckets/:bucketUuid/files/:fileUuid" \
--header "Authorization: Basic :credentials" \
--data-raw ""
{
  "id": "bc92ff8d-05f2-4380-bb13-75a1b6b7f388",
  "status": 200,
  "data": true
}

Delete directory

Deletes a directory from the storage bucket.

DELETE storage/buckets/:bucketUuid/directories/:directoryUuid

URL parameters

NameDescriptionrequired
bucketUuidUnique key of bucket. Key is displayed on developer dashboard.true
directoryUuidDirectory unique identifier.true

Possible errors

CodeDescription
40406003Directory does not exist.
40006007Directory is already marked for deletion.

Response fields

The response of the delete function is a boolean value, depends on whether the deletion was successful.


curl --location --request DELETE "https://api.apillon.io/storage/buckets/:bucketUuid/directories/:directoryUuid" \
--header "Authorization: Basic :credentials" \
--data-raw ""
{
  "id": "bc92ff8d-05f2-4380-bb13-75a1b6b7f388",
  "status": 200,
  "data": true
}

Get storage info

Gets overall storage info for a project.

Note: Available resources can be increased with a subscription to paid plans.

GET /storage/info

Response fields

FieldTypeDescription
availableStorageintegerAvailable storage space in bytes
usedStorageintegerUsed storage in bytes. When usedStorage reaches available storage, upload to buckets will be blocked (error 40006003)
availableBandwidthintegerMonthly available bandwidth (upload and download)
usedBandwidthintegerBandwidth used in current month. If usedBandwidth reaches available, requests to the IPFS gateway will be blocked

curl --location --request GET "https://api.apillon.io/storage/info" \
--header "Authorization: Basic :credentials"
{
  "id": "48e58f84-403a-43e4-bd81-fedeca195610",
  "status": 200,
  "data": {
    "availableStorage": 3221225472,
    "usedStorage": 1221225466,
    "availableBandwidth": 3221225472,
    "usedBandwidth": 56500
  }
}

Get IPFS cluster info

Gets basic data of an IPFS cluster used by the project. IPFS clusters contain multiple IPFS nodes but expose a single gateway for accessing content via CID or IPNS. Apillon clusters (gateways) are not publicly accessible

Note: Each project has its own secret for the generation of the tokens to access content on the IPFS gateway.

GET /storage/ipfs-cluster-info

Response fields

FieldTypeDescription
secretstringSecret for this project, which can be used to generate tokens to access content of IPFS gateway
projectUuidstringProject unique identifier
ipfsGatewaystringGateway that can used to access content via CIDs.
ipnsGatewaystringGateway that can be used to access content via IPNS name.

curl --location --request GET "https://api.apillon.io/storage/ipfs-cluster-info" \
--header "Authorization: Basic :credentials"
{
  "id": "0d7979c0-a00b-4502-9cb9-22228b24f71d",
  "status": 200,
  "data": {
    "secret": "*********",
    "project_uuid": "73f46f28-0d7c-43c4-9420-d4225b942ed1",
    "ipfsGateway": "https://<CIDv1>.staging.web3approved.com",
    "ipnsGateway": "https://<IPNS>.staging.web3approved.com"
  }
}

Apillon IPFS gateways are private and can only be accessible with a token. A token for specific address (CID) can be acquired via Apillon API request or can be generated with by using the secret and project_uuid properties from above request

GET /storage/link-on-ipfs/:cid

URL parameters

NameDescriptionrequired
cidIpfs content identifier. API will automatically detect the type (CIDv0, CIDv1 or IPNS)true

Response fields

FieldTypeDescription
linkstringLink where requested content can be accessed.

How to generate token programmatically

Apillon IPFS gateways accept JWT tokenopen in new window, which can be created using jsonwebtokenopen in new window package.

The JWT sign method expects three (3) parameters:

  1. JWT payload:
{
  "cid": "CID or IPNS address",
  "project_uuid": "Change with projectUuid value"
}
  1. Secret: Use secret property from IPFS cluster info
  2. Subject: IPFS-token

For each CID, a new token should be generated. Append the generated JWT to URL request as token query parameter.


curl --location --request GET "https://api.apillon.io/storage/link-on-ipfs/:cid" \
--header "Authorization: Basic :credentials"
{
  "id": "3a3ea750-3f3a-41e3-b5cb-a5543c2b2283",
  "status": 200,
  "data": {
    "link": "https://bafybeigjhyc2tpvqfqsuvf3byo4e4a4v6spi6jk4qqvvtlpca6rsaf2cqi.ipfs.web3approved.com/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJiYWZ5YmVpZ2poeWMydHB2cWZxc3V2ZjNieW80ZTRhNHY2c3BpNmprNHFxdnZ0bHBjYTZyc2FmMmNxaSIsInByb2plY3RfdXVpZCI6IjE0NmM5ZWU5LTEwMDgtNDdiNS05ZTJjLTQxZmIyN2ExZjY1NSIsImlhdCI6MTcwMjU1NTA2Mywic3ViIjoiSVBGUy10b2tlbiJ9.07tHk5jAuAbcRaDxiiA9zHNWD71pxAcQX9v7LbhZ0-E"
  }
}

IPNS

List IPNS names

API to list all IPNS names in a bucket. Items are paginated and can be filtered and ordered through query parameters. This is a listing request.

GET /storage/buckets/:bucketUuid/ipns

URL parameters

NameDescriptionRequired
bucketUuidUnique key of storage bucket, from which IPNS will be listedtrue

Query parameters

All query parameters from listing request plus:

NameDescriptionRequired
ipnsNameList IPNS names with specific namefalse
ipnsValueList IPNS names that point to this value (CID)false

Response fields (ipns)

Each item is an instance of the IPNF model, with the following properties:

FieldTypeDescription
createTimeDateTimeItem create time
updateTimeDateTimeItem last update time
ipnsUuidstringIPNS unique identifier
namestringInformational IPNS name, which is set by a user to easily organize the IPNS records
descriptionstringIPNS description
ipnsNamestringIPNS name used to access IPNS content on IPFs gateway
ipnsValuestringIPFS value (CID), to which this ipns points
linkstringIPNS link to Apillon IPFS gateway, allowing to access content to which this IPNS points

curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/ipns" \
--header "Authorization: Basic :credentials"
curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/ipns?ipnsName=k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk" \
--header "Authorization: Basic :credentials"
{
  "id": "f0764846-41f4-4352-87b4-85f9c94a8af4",
  "status": 200,
  "data": {
    "items": [
      {
        "createTime": "2023-11-24T06:22:16.000Z",
        "updateTime": "2023-11-24T06:22:16.000Z",
        "ipnsUuid": "9c0a0020-5d87-4112-a0ce-4033c037e31a",
        "name": "IPNS from Apillon API",
        "description": null,
        "ipnsName": null,
        "ipnsValue": null,
        "link": null
      },
      {
        "createTime": "2023-11-24T13:43:43.000Z",
        "updateTime": "2023-11-24T13:43:45.000Z",
        "ipnsUuid": "0b3c4ca8-3054-42a2-b5d4-1665646bbaa0",
        "name": "Example ipns",
        "description": null,
        "ipnsName": "k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk",
        "ipnsValue": "/ipfs/Qma6zTc8ctd65U2SARH7Qkssm6KrwsqJnX1PtrSqhXcM9L",
        "link": "https://ipfs-eu1.apillon.io/ipns/k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJrMms0cjhscXQwN2xzOXV5ejE0MW9mcWNsOTlrNGI4ZTYzbnMxZmg1MmliMWJ3aDA5ejBrNnZqayIsInByb2plY3RfdXVpZCI6ImQ3ZTlkZjQwLTcxNDgtNGYwZC1hMTEyLTM5YmYzMjY5NWFlNCIsImlhdCI6MTcwMDk4MTg3Niwic3ViIjoiSVBGUy10b2tlbiJ9.LMRhNNtsYF-0NlIcXFL1O85I58bsC_zHlbAepPz0hVM"
      }
    ],
    "total": 2
  }
}

Create new IPNS

API for creating a new IPNS record.

Note: IPNS becomes accessible on the IPFS gateway when content with CID is published to it. To access IPNS content on the IPFS gateway, use ipnsName.

POST /storage/buckets/:bucketUuid/ipns

URL parameters

NameDescriptionRequired
bucketUuidUnique key of storage bucket where IPNS will be created. Key is displayed on developer dashboard.true

Body fields

NameTypeDescriptionRequired
namestringIPNS name.true
descriptionstringIPNS description.false
cidstringCID to which the IPNS name will point. If this property is specified, API executes IPNS publish, which sets the ipnsName and ipnsValue properties.false

Possible errors

CodeDescription
42200026Request body is missing a name field.
40406002Bucket not found

Response

Response is an instance of IPNS described above.


curl --location --request POST "https://api.apillon.io/storage/buckets/:bucketUuid/ipns" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"name\": \"Example IPNS\",
    \"cid\": \"Qma6zTc8ctd65U2SARH7Qkssm6KrwsqJnX1PtrSqhXcM9L\"
}"
{
  "id": "0f436448-7c05-4f29-ae49-c57f55e36705",
  "status": 201,
  "data": {
    "createTime": "2023-11-24T12:14:31.127Z",
    "updateTime": null,
    "ipnsUuid": "0b3c4ca8-3054-42a2-b5d4-1665646bbaa0",
    "projectUuid": "d7e9df40-7148-4f0d-a112-39bf32695ae4",
    "bucketId": 11,
    "name": "Example ipns",
    "description": null,
    "ipnsName": "k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk",
    "ipnsValue": "/ipfs/Qma6zTc8ctd65U2SARH7Qkssm6KrwsqJnX1PtrSqhXcM9L",
    "link": "https://ipfs-eu1.apillon.io/ipns/k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJrMms0cjhscXQwN2xzOXV5ejE0MW9mcWNsOTlrNGI4ZTYzbnMxZmg1MmliMWJ3aDA5ejBrNnZqayIsInByb2plY3RfdXVpZCI6ImQ3ZTlkZjQwLTcxNDgtNGYwZC1hMTEyLTM5YmYzMjY5NWFlNCIsImlhdCI6MTcwMDk4MTg3Niwic3ViIjoiSVBGUy10b2tlbiJ9.LMRhNNtsYF-0NlIcXFL1O85I58bsC_zHlbAepPz0hVM"
  }
}

Get IPNS

API to get specific IPNS name by its UUID.

GET /storage/buckets/:bucketUuid/ipns/:ipnsUuid

URL parameters

NameDescriptionRequired
bucketUuidUnique key of storage buckettrue
ipnsUuidUnique key of IPNS nametrue

Possible errors

CodeDescription
40406012IPNS not found

Response fields (IPNS)

Response is an instance of IPNS described above.


curl --location --request GET "https://api.apillon.io/storage/buckets/:bucketUuid/ipns/:ipnsUuid" \
--header "Authorization: Basic :credentials"
{
  "id": "0f436448-7c05-4f29-ae49-c57f55e36705",
  "status": 201,
  "data": {
    "createTime": "2023-11-24T12:14:31.127Z",
    "updateTime": null,
    "ipnsUuid": "0b3c4ca8-3054-42a2-b5d4-1665646bbaa0",
    "projectUuid": "d7e9df40-7148-4f0d-a112-39bf32695ae4",
    "bucketId": 11,
    "name": "Example IPNS",
    "description": null,
    "ipnsName": "k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk",
    "ipnsValue": "/ipfs/Qma6zTc8ctd65U2SARH7Qkssm6KrwsqJnX1PtrSqhXcM9L",
    "link": "https://ipfs-eu1.apillon.io/ipns/k2k4r8lqt07ls9uyz141ofqcl99k4b8e63ns1fh52ib1bwh09z0k6vjk/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJrMms0cjhscXQwN2xzOXV5ejE0MW9mcWNsOTlrNGI4ZTYzbnMxZmg1MmliMWJ3aDA5ejBrNnZqayIsInByb2plY3RfdXVpZCI6ImQ3ZTlkZjQwLTcxNDgtNGYwZC1hMTEyLTM5YmYzMjY5NWFlNCIsImlhdCI6MTcwMDk4MTg3Niwic3ViIjoiSVBGUy10b2tlbiJ9.LMRhNNtsYF-0NlIcXFL1O85I58bsC_zHlbAepPz0hVM"
  }
}

Publish IPNS

API for publishing IPNS on IPFS and linking it to CID.

Note: Multiple IPNS records can point to the same CID.

POST /storage/buckets/:bucketUuid/ipns/:ipnsUuid/publish

URL parameters

NameDescriptionRequired
bucketUuidUnique key of storage bucket.true
ipnsUuidUnique key of IPNS record that will be publishedtrue

Body fields

NameTypeDescriptionRequired
cidstringCID to which the IPNS name will point.true

Possible errors

CodeDescription
42200030Body is missing CID property
40406012IPNS not found

Response

The response is an instance of IPNS that was published. Properties are described above.


curl --location --request POST "https://api.apillon.io/storage/buckets/:bucketUuid/ipns/:ipnsUuid/publish" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"cid\": \"Qma6zTc8ctd65U2SARH7Qkssm6KrwsqJnX1PtrSqhXcM9L\"
}"
{
  "id": "14bfe999-ffc4-477b-bf10-4fe9ba9ab90a",
  "status": 200,
  "data": {
    "createTime": "2023-11-26T07:13:32.000Z",
    "updateTime": "2023-11-26T07:13:32.000Z",
    "ipnsUuid": "df5c47b4-e00b-4163-877e-7c78042e7666",
    "name": "My 3 IPNS",
    "description": null,
    "ipnsName": "k2k4r8jofss9us61kwlmq8flgdhj3a1tn5ikcc6m494kf2edifi2oh4z",
    "ipnsValue": "/ipfs/Qma6zTc8ctd65U2SARH7Qkssm6KrwsqJnX1PtrSqhXcM9L",
    "link": "https://ipfs-eu1.apillon.io/ipns/k2k4r8jofss9us61kwlmq8flgdhj3a1tn5ikcc6m494kf2edifi2oh4z/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJrMms0cjhqb2Zzczl1czYxa3dsbXE4ZmxnZGhqM2ExdG41aWtjYzZtNDk0a2YyZWRpZmkyb2g0eiIsInByb2plY3RfdXVpZCI6ImQ3ZTlkZjQwLTcxNDgtNGYwZC1hMTEyLTM5YmYzMjY5NWFlNCIsImlhdCI6MTcwMTA3NTk3OCwic3ViIjoiSVBGUy10b2tlbiJ9.xJ0ZdUb0XqH9oe7AvG0yUnCnydKNoGlNnNsIYZEwAc0"
  }
}

Delete IPNS

API to delete IPNS record.

DELETE /storage/buckets/:bucketUuid/ipns/:ipnsUuid

URL parameters

NameDescriptionRequired
bucketUuidUnique key of storage buckettrue
ipnsUuidUnique key of IPNS recordtrue

Possible errors

CodeDescription
40406012IPNS not found

Response fields (IPNS)

The response is deleted IPNS record, an instance of IPNS described above.


curl --location --request DELETE "https://api.apillon.io/storage/buckets/:bucketUuid/ipns/:ipnsUuid" \
--header "Authorization: Basic :credentials"
{
  "id": "302f036b-5ca5-488c-bbd5-a7cdd7674898",
  "status": 200,
  "data": {
    "createTime": "2023-11-24T06:22:16.000Z",
    "updateTime": "2023-11-24T06:22:16.000Z",
    "ipnsUuid": "9c0a0020-5d87-4112-a0ce-4033c037e31a",
    "name": "IPNS from Apillon API",
    "description": null,
    "ipnsName": null,
    "ipnsValue": null
  }
}