Demo
This section demonstrates how to interact with the API using practical command-line examples.
Explore the endpoints below to learn how to easily communicate with any Aruna node.
Info Endpoint
Get general info about a specific Node
Use this endpoint to retrieve basic information about the requested node, including the Realm it belongs too, its id and network addresses.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8081/api/v3/info'
Response
{
"realm_id": "b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900",
"node_id": "a16395bd7963f6c618fadb266e0f5f52b98cbeacade7cf80449c6ce42c61d7d1",
"node_addr": {
"node_id": "a16395bd7963f6c618fadb266e0f5f52b98cbeacade7cf80449c6ce42c61d7d1",
"relay_url": null,
"direct_addresses": [
"134.176.138.7:1231",
"172.17.0.1:1231",
"172.18.0.1:1231"
]
}
}
Get general info about a specific Realm
Use this endpoint to retrieve basic information about the requested Realm.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>/api/v3/info/realm'
Response
{
"nodes": [
{
"realm_id": "b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900",
"node_id": "8e5c2c3e4771f91e7af9dd70a48cee50cb67070c3bef6ed9fcad821c85874b0f",
"node_addr": {
"node_id": "8e5c2c3e4771f91e7af9dd70a48cee50cb67070c3bef6ed9fcad821c85874b0f",
"relay_url": null,
"direct_addresses": [
"134.176.138.7:1230",
"172.17.0.1:1230",
"172.18.0.1:1230"
]
}
},
{
"realm_id": "b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900",
"node_id": "a16395bd7963f6c618fadb266e0f5f52b98cbeacade7cf80449c6ce42c61d7d1",
"node_addr": {
"node_id": "a16395bd7963f6c618fadb266e0f5f52b98cbeacade7cf80449c6ce42c61d7d1",
"relay_url": null,
"direct_addresses": [
"134.176.138.7:1231",
"172.17.0.1:1231",
"172.18.0.1:1231"
]
}
},
{
"realm_id": "b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900",
"node_id": "d3d0a9d61994ca137542b7267e95bf5a00cc0b6d51170f5b2c3c8adbfcbd5a0f",
"node_addr": {
"node_id": "d3d0a9d61994ca137542b7267e95bf5a00cc0b6d51170f5b2c3c8adbfcbd5a0f",
"relay_url": null,
"direct_addresses": [
"134.176.138.7:1232",
"172.17.0.1:1232",
"172.18.0.1:1232"
]
}
}
]
}
Search for resources by keyword(s)
Use this endpoint to search with keywords for metadata resources
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X 'GET' 'http://<node-host>:8081/api/v3/info/search?query=ecoli'
Response
{
"resources": [
{
"id": "string",
"name": "string",
"description": "string",
"revision": 9007199254740991,
"authors": [
{
"id": "string",
"first": "string",
"last": "string"
}
],
"content_len": 9007199254740991,
"count": 9007199254740991,
"created_at": "2025-09-19T10:24:53.193Z",
"data": [
{
"ContentHash": {
"datahash": "string"
}
},
{
"Link": "string"
}
],
"deleted": true,
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
"last_modified": "2025-09-19T10:24:53.193Z",
"license_id": "string",
"locked": true,
"title": "string",
"variant": "Project",
"visibility": "Public"
}
]
}
Users Endpoint
Add a new user
A new user needs to register via this endpoint. This returns a token, that can be used on any endpoint on the p2p network.
Request
curl -d '
{
"name": "Jannis Schlegel"
}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X POST 'http://<node-host>:8081/api/v3/users'
Response
{
"token": "<your-initial-secret-token>",
"user": {
"id": "01K5EDZ8W7HRME69TM9SZ76YNB@b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900",
"name": "Jannis Schlegel",
"realm_key": [
1073741824
]
}
}
Query a user
A user can be queried via this endpoint. In the future this endpoint can be used by group admins to query information about any group members or users with public information.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8083/api/v3/users?id={user-identity}'
Response
{
"realm_id": "b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900",
"user_id": "01K5EDZ8W7HRME69TM9SZ76YNB@b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900>",
"user_name": "Jannis Schlegel"
}
Groups Endpoint
Create a new Group
This endpoint can be used to create a new group. Groups form the basis of authorization and authentication for resources in aruna.
Request
curl -d '
{
"name": "my_group"
}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X POST 'http://<node-host>:8081/api/v3/groups'
Response
{
"group": {
"id": "01K60DD03CHA6ZZ3T01NDDPXN0",
"realm_key": [180, 230, 49, ...],
"name": "my_group",
"roles": [
"admin",
"member"
],
"members": {
"01K60DC77A5YCZH1Q2SKX73C3M@b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900": [
"admin"
]
}
}
}
Get info of a Group
Group information can be queried on this endpoint.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8081/api/v3/groups?id=01K60DD03CHA6ZZ3T01NDDPXN0'
Response
{
"group": {
"id": "01K60DD03CHA6ZZ3T01NDDPXN0",
"realm_key": [180, 230, 49, ...],
"name": "my_group",
"roles": [
"admin",
"member"
],
"members": {
"01K60DC77A5YCZH1Q2SKX73C3M@b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900": [
"admin"
]
}
}
}
Add User to a Group
Users can be added via AddUserRequests by group admins.
Request
curl -d '
{
"group_id": "01K60DD03CHA6ZZ3T01NDDPXN0",
"user_roles": {
"member": [
"01K60DQTQSSW6CT7V6254XR91P@b4e63113c8f2d85f743841abecd8b10a873aa43207306d86c212967c9a8c1900"
]
}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-H 'Content-Type: application/json' \
-X POST 'http://<node-host>:8081/api/v3/groups/user'
Response
{}
Resources Endpoint
Create a new metadata project
A metadata project is the root ro-crate for a metadata collection. There is no need to create nested resources, because multiple datasets cann be added and annotated in one single metadata resource. Nesting is still possible to further structure your metadata or to scale things up if metadata gets large.
Request
curl -X 'POST' 'http://<node-host>:8081/api/v3/resources/project' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-H 'Content-Type: application/json' \
-d '
{
"authors": [
{
"first": "string",
"id": "string",
"last": "string"
}
],
"description": "string",
"group_id": "string",
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
"license_id": "string",
"name": "string",
"title": "string",
"visibility": "Public"
}'
Response
{
"resource": {
"id": "string",
"name": "string",
"title": "string",
"description": "string",
"revision": 0,
"variant": "Project",
"visibility": "Public",
"content_len": 123456,
"count": 0,
"created_at": "2025-09-29T06:47:25.047Z",
"last_modified": "2025-09-29T06:47:25.047Z",
"license_id": "string",
"locked": false,
"deleted": false,
"authors": [
{
"id": "string",
"first": "string",
"last": "string"
}
],
"data": [
{
"ContentHash": {
"datahash": "string"
}
},
{
"Link": "string"
}
],
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
}
}
Create a new metadata resource
Nested metadata resources can be appended to already existing metadata projects.
Request
curl -d '
{
"authors": [
{
"id": "string",
"first": "string",
"last": "string"
}
],
"description": "string",
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
"license_id": "string",
"name": "string",
"parent_id": "string",
"title": "string",
"variant": "Folder",
"visibility": "Public"
}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X POST 'http://<node-host>:8081/api/v3/resources'
Response
{
"resource": {
"id": "string",
"name": "string",
"title": "string",
"description": "string",
"revision": 0,
"variant": "Project",
"visibility": "Public",
"content_len": 123456,
"count": 0,
"created_at": "2025-09-29T06:47:25.047Z",
"last_modified": "2025-09-29T06:47:25.047Z",
"license_id": "string",
"locked": false,
"deleted": false,
"authors": [
{
"id": "string",
"first": "string",
"last": "string"
}
],
"data": [
{
"ContentHash": {
"datahash": "string"
}
},
{
"Link": "string"
}
],
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
}
}
Get info of an existing metadata resource
Any metadata object can be queried from any node with a simple get request and the resource id.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8081/api/v3/resources?id=01K6AA6D7G48GNYMFD8G03QPWP'
Response
{
"resource": {
"id": "string",
"name": "string",
"title": "string",
"description": "string",
"revision": 0,
"variant": "Project",
"visibility": "Public",
"content_len": 123456,
"count": 0,
"created_at": "2025-09-29T06:47:25.047Z",
"last_modified": "2025-09-29T06:47:25.047Z",
"license_id": "string",
"locked": false,
"deleted": false,
"authors": [
{
"id": "string",
"first": "string",
"last": "string"
}
],
"data": [
{
"ContentHash": {
"datahash": "string"
}
},
{
"Link": "string"
}
],
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
}
}
Get change history of a metadata resource
The change history of every action that was called on a specific resource can be displayed with a query in the history endpoint.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8081/api/v3/resources/history?id=01K6AA6D7G48GNYMFD8G03QPWP'
Response
{
"history": [
{
"actor_id": {
"node_id": "string",
"realm_key": "string",
"user_identity": "string"
},
"deps": [
"string"
],
"extra_bytes": [
1073741824
],
"hash": "string",
"message": "string",
"operations": [
"string"
],
"seq": 10,
"start_op": 9007199254740991,
"time": 9007199254740991
}
]
}
Update title of a metadata resource
Metadata fields are currently updated with a specfic endpoint for each field. This will change over time to allow for more flexible json-based metadata edits
Request
curl -d '
{
"id": "01K6AA6D7G48GNYMFD8G03QPWP",
"title": "Some new title"
}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X POST 'http://<node-host>:8081/api/v3/resources/title'
Response
{
"resource": {
"id": "01K6AA6D7G48GNYMFD8G03QPWP",
"name": "string",
"title": "Some new title",
"description": "string",
"revision": 0,
"variant": "Project",
"visibility": "Public",
"content_len": 123456,
"count": 0,
"created_at": "2025-09-29T06:47:25.047Z",
"last_modified": "2025-09-29T06:47:25.047Z",
"license_id": "string",
"locked": false,
"deleted": false,
"authors": [
{
"id": "string",
"first": "string",
"last": "string"
}
],
"data": [
{
"ContentHash": {
"datahash": "string"
}
},
{
"Link": "string"
}
],
"identifiers": [
"string"
],
"labels": [
{
"key": "string",
"value": "string"
}
],
}
}
Create s3 credentials
S3 Credentials for a user are always group specific. They can be created for any node in the registered realm.
Request
curl -d '
{
"group_id": "string"
}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X POST 'http://<node-host>:8080/api/v3/users/credentials'
Response
{
"access_key_id": "<your-access-key-id>",
"secret_access_key": "<your-secret-access-key>""
}
Get S3 credentials
Your already created credentials can always be displayed with a `GetCredentialsRequest`. Credentials are only valid for each individual node.
Request
curl -H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8080/api/v3/users/credentials'
Response
{
"access_key_id": "<your-access-key-id>",
"secret_access_key": "<your-secret-access-key>""
}
Deleting S3 credentials
Credentials can be deleted on nodes with a `DeleteCredentialsRequest`.
Request
curl -H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X DELETE 'http://<node-host>:8080/api/v3/users/credentials' \
Response
{}
Get data locations
Existing data locations can be queried by their respective content-hashes. In a flexible p2p system like aruna this is especially useful to automate actions based on resource locality.
Request
curl -H 'accept: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X GET 'http://<node-host>:8080/api/v3/data/location?hash=ebae78bcd5a3ef259a4da35b3ac39ea29b8e147eb288c69404dd1bfa58280df4'
Response
{
"location": [
{
"direct_addresses": [
"0.0.0.0:1230"
],
"node_id": "",
"relay_url": "null"
}
]
}
Register data from storage backend
Existing data sources you have access to can be registered via this endpoint. This currelntly only works for individual objects, but gets further extended in the future.
Request
curl -d '
{
"backend_path": "/some-path/to/the/data.log",
"bucket": "my_bucket",
"create_s3_path": true,
"group_id": "01K60DD03CHA6ZZ3T01NDDPXN0",
"key": "<some-s3-key-id>"
}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-secret-token>' \
-X POST http://<node-host>:8080/api/v3/users/credentials'
Response
{
"access_key_id": "<some-ulid>>",
"secret_access_key": "<some-secret-key>"
}
S3 Endpoint
To interact with the s3 endpoint you need a s3 client. Our recommendation for this demo is the official aws cli. Other clients should work, but are not tested and most of them are not feature complete.
Creating s3 buckets
A bucket can be created without any other restriction other than having valid S3 credentials
Request
aws --endpoint-url http://<node-s3-endpoint> \
--profile <aws-credentials-profile> \
--no-verify-ssl \
s3 mb s3://<your-bucket-name>
Response
make_bucket: <your-bucket-name>
Data uploads
Data uploads (single and multipart) are done with the s3 put convenience function.
Request
aws --endpoint-url http://<node-s3-endpoint> \
--profile <aws-credentials-profile> \
--no-verify-ssl \
s3 cp <your-local-object> s3://<your-bucket-name>/<your-remote-name>
Response
upload: ./<your-local-object> to s3://<your-bucket-name>/<your-remote-name>
Data downloads
Data can be downloaded the same way data is uploaded.
Request
aws --endpoint-url http://<node-s3-endpoint> \
--profile <aws-credentials-profile> \
--no-verify-ssl \
s3 cp s3://<your-bucket-name>/<your-remote-name> <your-local-object>
Response
download: ./<your-local-object> to s3://<your-bucket-name>/<your-remote-name>
Data replication
Data can be replicated to other nodes via the put-bucket-replication interface of s3.
Request
aws --endpoint-url http://<node-s3-endpoint> \
--profile <aws-credentials-profile> \
--no-verify-ssl \
s3api put-bucket-replication \
--bucket <your-bucket-name> \
--replication-configuration '
{
"Role": "arn:aws:s3:::",
"Rules": [
{
"ID": <your-replication-rule-name>,
"Destination": {
"Bucket": "arn:aws:s3:<target-node-id>:account_id:<target-bucket>"
},
"Status": "Enabled"
}
]
}'
Response
{}
Querying replication rules
Data replication rules can be viewed with this request.
Request
aws --endpoint-url http://<node-s3-endpoint> \
--profile <aws-credentials-profile> \
--no-verify-ssl \
s3api get-bucket-replication \
--bucket <your-bucket-name>
Response
{
"ReplicationConfiguration": {
"Role": <your-user-id>,
"Rules": [
{
"Status": "ENABLED",
"ExistingObjectReplication": {
"Status": "false"
},
"Destination": {
"Bucket": <your-bucket-name>
}
}
]
}
}