IPFS-Gateway / file access in actyx v2

Hi all

i am currently upgrading to actyx v2.

In actyx v1 we had an ipfs node connected to the swarm, files were added to that ipfs node.
I then could access these file via the ipfs gateway port 8080 on the local actyx node (http://localhost:8080/ipfs/<hash>).

Can i do that with actyx v2 as well? Port 8080 seems to be no longer available.

thanks for any help


Hi @michael.porr,

with Actyx v2.8.0, we’ve release the Files API that allows you to do that. Shout-out to @wngr who made that happen :pray:. However, it does not seem to have made it into the documentation, yet. Apologies for that!

Here’s a quick introduction what you can do with it to get you started. Hope that helps.

Files API


  • Files can be uploaded as multipart/formdata.
  • To make uploading more convenient than using curl, I’ve attached a sample uploader HTML page to allow for uploading files and folder hierarchies more easily.
  • Uploading a file returns a content identifier (CID), which is a unique hash based on the file’s content.
  • Files can be accessed either via
    http://localhost:4454/api/v2/files/<cid>/<optional path> or via
    http://<cid>.actyx.localhost::4454/<optional path>. This enables serving
    webapps from the content root conveniently.
  • The Actyx Naming Service (ANS) allows you to attach a name to a CID and access the content using that name through http://<name>.actyx.localhost:4454/<optional path>. You can also update that name to point to a different CID, allowing you to roll out new versions of a file/app.
  • The authentication token for Actyx API access can be provided through the ?token=... query parameter.


  1. Get an authentication token using an Actyx manifest and store it in the AUTH_TOKEN variable. Uses curl to make the request and jq to parse the result.
$ export AUTH_TOKEN=$(echo '
    "appId": "com.example.actyx-v1-pond",
    "displayName": "V1 Pond API compatible with V2 store",
    "version": "1.0"
' \
| curl \
    -s -X "POST" \
    -d @- \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    http://localhost:4454/api/v2/auth \
| jq -r .token)
  1. Upload the attached file uploader HTML.
$ curl -X POST \
   -H "Authorization: Bearer $AUTH_TOKEN" \
   -F file=@upload_files.html \

bafybeiaqela5uulk5qycsxncdtv36stuowojyuso3dnwlaninksco5cfpi # Returns the CID of the uploaded file
  1. Assign a name to the CID returned in the previous step, with uploader being the name to assign. You’ll see HTTP/1.1 200 OK somewhere in the output if the upload went through as expected.
$ echo bafybeiaqela5uulk5qycsxncdtv36stuowojyuso3dnwlaninksco5cfpi | \
  curl -s -X PUT \
  -d @- \
  -H "Authorization: Bearer $AUTH_TOKEN"  \
  http://localhost:4454/api/v2/files/uploader -v
  1. Open the uploader using the name you assigned earlier, http://uploader.actyx.localhost:4454/.

  2. Upload files or SPA folders as you see fit, noting their CIDs in case you want to name them as well. Use drag’n’drop to add files, enter your auth token (see step 1) in the corresponding field and click upload.

  3. You can now go ahead, add new content again and/or assign names to existing CIDs as described before (or build an uploader that takes care of this :-)), e.g.

echo bafybeieod6ngzponojuau3vwxshptnwqcdoa436obbgv3z2jluxzlc4wqy | \
  curl -s -X PUT \
  -d @- \
  -H "Authorization: Bearer $AUTH_TOKEN"  \


upload_files.html.zip (2.2 KB)

Ah ok, thanks for that. I will have a look into it.

Is the files api also part of @actyx/pond or @actyx/sdk?

There is no direct support in the SDK, AFAIK. It’s on the same level as the Events, Auth, and Node HTTP APIs.
As the concept (supporting file sharing and deployment) is orthogonal to building applications, I assume there won’t be any additions to the SDK in this regard.

Hi @michael.porr, have you tried the approach? Does it work for you?
If so, would you be so kind as to mark it as solution so others who look at the post in the future know it’s a useful answer?

Thanks :pray:

Haven’t tried it yet but i guess it will be the solution…

The Files API now also made its way into the official docs: Files API | Actyx Developer