Simple uploads

How can I upload files to Akord's Arweave storage? How can I upload files to Akord's cloud storage?

Example 1.1. Minimal upload

Bash

curl --location 'https://api.akord.com/files' \
--header 'Accept: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Content-Type: text/plain' \
--data '@/path/to/your/file.txt'

JavaScript

const fs = require('fs').promises;
const data = await fs.readFile('/path/to/your/file.txt', 'utf8'); //nodejs specific

const response = await fetch('https://api.akord.com/files', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    },
    body: data
})

Python

import requests

with open('/path/to/your/file.txt', 'r', encoding='utf-8') as file:
    data = file.read()

response = requests.post(
    url='https://api.akord.com/files', 
    headers={
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    }, 
    data=data
)

Thats it! You just uploaded the file to Arweave. Here is the example response:

{
    "id": "a6f1fbfc-403d-4607-b648-4b949fdd50bd", 
    //technical id of upload. can be used to get metadata of the upload or file binary from cloud storage
    
    "mime_type": "text/plain", //depends on content-type of upload, goes as a tag 
    "sizeInBytes": 10,
    "cloud": {
        "uri": "a6f1fbfc-403d-4607-b648-4b949fdd50bd", //same as ID
        "url": "https://api.akord.com/files/a6f1fbfc-403d-4607-b648-4b949fdd50bd"                 //url to binary served from cloud storage
    },
    "tx": {
        "id": "LAWVdsBRTkUF8ptiEwiU6n4Q-_5ukBJIFmeAllX7Q0E", //fixed ID of Arweave transaction (ANS-104 data item ID)
        "status": "scheduled", 
        //indicates where is your file in Arweave bundling context
        //scheduled - file is in our cloud storage and is scheduled for ANS-104 
        //verification - file is being verified for malicious content
        //blocked - file is recognized as malicious, won't go to Arweave
        //pending - file was bundled and posted to Arweave
        //confirmed - file is confirmed on Arweave
        //rejected - this indicates a technical problem with our bundling service)
        "tags": [], //your Arweave tags appended to transaction
        "statusUrl": "https://api.akord.com/files/a6f1fbfc-403d-4607-b648-4b949fdd50bd/status", //check file status endpoint, returns simillar JSON schema
        "gatewayUrls": [
            "https://akrd.net/LAWVdsBRTkUF8ptiEwiU6n4Q-_5ukBJIFmeAllX7Q0E", 
            //our instance of Arweave gateway - this url will work always, even right after upload since it falls back to cloud storage when file is not yet on Arweave
            "https://arweave.net/LAWVdsBRTkUF8ptiEwiU6n4Q-_5ukBJIFmeAllX7Q0E" 
            // other Arweave gatways
        ]
        "viewblockUrl": "https://viewblock.io/arweave/tx/LAWVdsBRTkUF8ptiEwiU6n4Q-_5ukBJIFmeAllX7Q0E", //see your file on Viewblock - this url will only work when file is in 'committed' status & indexed by Viewblock
        "info": "Transaction is visible on the blockchain indexers when in the \"committed\" status.",
        "infoUrl": "https://docs.akord.com/api-and-dev-tools/build/akord-api/files"
    }
}

Example 1.2. Upload with Arweave transaction tags

To add tags to your Arweave transaction - use query params. Each query param with key prefixed with tag- is treated as Arweave transaction tags. Tags query params are case sensitive. E.g.

tag-file-category=photo => Tag name: 'file-category', Tag value: 'photo'

Tag-File-Category=PHOTO => Tag name: 'File-Category', Tag value: 'PHOTO'

Bash

curl --location 'https://api.akord.com/files?tag-file-category=photo&tag-file-description=wedding%202024' \
--header 'Accept: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Content-Type: image/png' \
--data '@/path/to/your/file.png'

Javascript

const fs = require('fs').promises;
const data = await fs.readFile('/path/to/your/file.txt', 'utf8'); //nodejs specific

const response = await fetch('https://api.akord.com/files?tag-file-category=photo&tag-file-description=wedding%202024', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    },
    body: data
})

Python

import requests

with open('/path/to/your/file.txt', 'r', encoding='utf-8') as file:
    data = file.read()

response = requests.post(
    url='https://api.akord.com/files?tag-file-category=photo&tag-file-description=wedding%202024', 
    headers={
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    }, 
    data=data
)

{
    "id": "a2a48bc6-7e9f-48c6-abc7-9e641390680b",
    "mimeType": "image/png",
    "sizeInBytes": 437432,
    "cloud": {
        "uri": "a2a48bc6-7e9f-48c6-abc7-9e641390680b",
        "url": "https://api.akord.com/files/a2a48bc6-7e9f-48c6-abc7-9e641390680b"
    },
    "tx": {
        "id": "ewR2EcQJOSAN-dH0GZVswOG_g_kjtFh_dUSrjpbd_Lo",
        "status": "scheduled",
        "tags": [
            {
                "name": "file-category",
                "value": "photo"
            },
            {
                "name": "file-description",
                "value": "wedding 2024"
            }
        ],
        "statusUrl": "https://api.akord.com/files/a2a48bc6-7e9f-48c6-abc7-9e641390680b/status",
        "gatewayUrls": [
            "https://akrd.net/ewR2EcQJOSAN-dH0GZVswOG_g_kjtFh_dUSrjpbd_Lo",
            "https://arweave.net/ewR2EcQJOSAN-dH0GZVswOG_g_kjtFh_dUSrjpbd_Lo"
        ],
        "viewblockUrl": "https://viewblock.io/arweave/tx/ewR2EcQJOSAN-dH0GZVswOG_g_kjtFh_dUSrjpbd_Lo",
        "info": "Transaction is visible on the blockchain indexers when in the \"committed\" status.",
        "infoUrl": "https://docs.akord.com/api-and-dev-tools/build/akord-api/files"
    }
}

Example 1.3. Upload with Arweave transaction tags (encoded)

You may encode your tags as base64 string and pass it as a single param

Bash

base64_encoded_tags=$(echo -n '[
    {
        "name": "file-category",
        "value": "photo"
    },
    {
        "name": "file-description",
        "value": "wedding 2024"
    }
]' | base64)

# Use in querystring
curl --location 'https://api.akord.com/files?tags=$base64_encoded_tags' \
--header 'Accept: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Content-Type: image/png' \
--data '@/path/to/your/file.png'

# Or use in header
curl --location 'https://api.akord.com/files' \
--header 'Accept: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Content-Type: image/png' \
--header 'Tags: $base64_encoded_tags' \
--data '@/path/to/your/file.png'

Javascript

const fs = require('fs').promises;

const tags = [
    {
        name: "file-category",
        value: "photo"
    },
    {
        name: "file-description",
        value: "wedding 2024"
    }
];

const jsonTags = JSON.stringify(tags);
const base64EncodedTags = Buffer.from(jsonTags).toString('base64url');

const data = await fs.readFile('/path/to/your/file.txt', 'utf8'); //nodejs specific

//Use in querystring
const response = await fetch(`https://api.akord.com/files?tags=${base64EncodedTags}`, {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    },
    body: data
})

//Or use in header
const response = await fetch(`https://api.akord.com/files`, {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
        'Tags': base64EncodedTags
    },
    body: data
})

Python

import json
import base64
import requests

tags = [
    {
        "name": "file-category",
        "value": "photo"
    },
    {
        "name": "file-description",
        "value": "wedding 2024"
    }
]

json_tags = json.dumps(data).encode('utf-8')
base64_encoded_tags = base64.urlsafe_b64encode(json_data).decode('utf-8')

with open('/path/to/your/file.txt', 'r', encoding='utf-8') as file:
    data = file.read()

#Use in querystring
response = requests.post(
    url=f"https://api.akord.com/files?tags={base64_encoded_tags}", 
    headers={
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    }, 
    data=data
)

#Or use in header
response = requests.post(
    url=f"https://api.akord.com/files", 
    headers={
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain',
        'Tags': base64_encoded_tags
    }, 
    data=data
)

Example 2. Upload to cloud storage

Bash

curl --location 'https://api.akord.com/files?storage-class=cloud' \
--header 'Accept: application/json' \
--header 'Api-Key: your_api_key' \
--header 'Content-Type: image/png' \
--data '@/path/to/your/file.png'

Javascript

const fs = require('fs').promises;
const data = await fs.readFile('/path/to/your/file.txt', 'utf8'); //nodejs specific

const response = await fetch('https://api.akord.com/files?storage-class=cloud', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    },
    body: data
})

Python

import requests

with open('/path/to/your/file.txt', 'r', encoding='utf-8') as file:
    data = file.read()

response = requests.post(
    url='https://api.akord.com/files?storage-class=cloud', 
    headers={
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'text/plain'
    }, 
    data=data
)

The request above stores the binary on ACS (Akord Cloud Storage) and does not trigger blockchain transaction. Cloud storage balance is consumed.

Example response:

{
    "id": "0976fac1-0d24-4a4e-b2bb-cd965840f656",
    "mimeType": "image/png",
    "sizeInBytes": 437432,
    "cloud": {
        "uri": "0976fac1-0d24-4a4e-b2bb-cd965840f656",
        "url": "https://api.akord.com/files/0976fac1-0d24-4a4e-b2bb-cd965840f656"
    }
}