Using the REST API#

Using the curl command in the terminal, we can access the Caterva2 REST API and query for example the list of available roots:

curl -X 'GET' \
  'https://cat2.cloud/demo/api/roots' \
  -H 'accept: application/json'

{
  "@public": {
    "name": "@public",
    "http": "",
    "subscribed": true
  }
}

We can query the list of files in the @public root via:

curl -X 'GET' \
  'https://cat2.cloud/demo/api/list/@public' \
  -H 'accept: application/json'

which gives:

[
  "examples/README.md",
  "examples/Wutujing-River.jpg",
  "examples/cat2cloud-brochure.pdf",
  "examples/dir1/ds-2d.b2nd",
...
  "examples/tomo-guess-test.b2nd",
  "la_blosclz.b2nd"
]

Let’s get some metadata for the "examples/dir1/ds-2d.b2nd" dataset:

curl -X 'GET' \
  'https://cat2.cloud/demo/api/info/@public/examples/dir1/ds-2d.b2nd' \
  -H 'accept: application/json'

{
  "shape": [
    10,
    20
  ],
  "chunks": [
    5,
    5
  ],
  "blocks": [
    2,
    3
  ],
  "dtype": "uint16",
  "schunk": {
    ...
  },
  "mtime": "2025-05-25T22:00:09.161597Z"
}

Finally we can download the dataset to a local file, localfile.b2nd, using:

curl -X 'GET' \
'https://cat2.cloud/demo/api/download/@public/examples/dir1/ds-2d.b2nd' \
  -H 'accept: application/json' --output "localfile.b2nd"

For further details see the Caterva2 REST API documentation, which can be used to automatically generate curl commands of the kind in this tutorial.

This Page