Files

Files are attachment resources rooted in the /v1/files/{org_label}/{project_label}/ collection.

Each file…

  • belongs to a project identifier by the label {project_label}
  • inside an organization identifier by the label {org_label}

Access to resources in the system depends on the access control list set for them. Depending on the access control list, a caller may need to prove its identity by means of an access token passed to the Authorization header (Authorization: Bearer {token}). Please visit Authentication to learn more about how to retrieve an access token.

Authorization notes

When modifying files, the caller must have projects/write permissions on the current path of the project or the ancestor paths.

When reading files, the caller must have projects/read permissions on the current path of the project or the ancestor paths.

Create a file using POST

POST /v1/files/{org_label}/{project_label}

The json payload:

  • If the @id value is found on the payload, this @id will be used.
  • If the @id value is not found on the payload, an @id will be generated as follows: base:{UUID}. The base is the prefix defined on the resource’s project ({project_label}).

Example

Request
curl -XPOST -F "file=@/path/to/myfile.jpg;type=image/jpeg" "https://nexus.example.com/v1/files/myorg/myproj"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Create a file using PUT

This alternative endpoint to create a resource is useful in case the json payload does not contain an @id but you want to specify one. The @id will be specified in the last segment of the endpoint URI.

PUT /v1/files/{org_label}/{project_label}/{file_id}

Note that if the payload contains an @id different from the {file_id}, the request will fail.

Example

Request
curl -XPUT -F "file=@/path/to/myfile.jpg;type=image/jpeg" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Create a file (specific storage)

POST /v1/files/{org_label}/{project_label}?storage={storageId}

Or

PUT /v1/files/{org_label}/{project_label}/{file_id}?storage={storageId}

… where {storageId} selects a specific storage backend where the file will be uploaded.

Example

Request
curl -XPOST -F "file=@/path/to/myfile.jpg;type=image/jpeg" "https://nexus.example.com/v1/files/myorg/myproj?storage=nxv:mys3storage"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Link an existing file using POST

Creates a resource from an existing file, provided that the storage backend where it is located supports the operation.

POST /v1/files/{org_label}/{project_label}?storage={storageId}
  {
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
  }

… where {storageId} selects a specific storage backend that supports linking existing files.

Example

Request
curl -XPOST "https://nexus.example.com/v1/files/myorg/myproj?storage=nxv:mys3storage" -d \
'{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}'
Full source at GitHub
Payload
{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.png",
  "_location": "https://s3.us-west-1.amazonaws.com/mybucket/relative/path/to/myfile.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Link an existing file using PUT

Creates a resource from an existing file, provided that the storage backend where it is located supports the operation.

This alternative endpoint allows to specify the resource @id.

PUT /v1/files/{org_label}/{project_label}/{file_id}?storage={storageId}
  {
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
  }

… where {storageId} selects a specific storage backend that supports linking existing files.

Example

Request
curl -XPUT "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.png?storage=nxv:mys3storage" -d \
'{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}'
Full source at GitHub
Payload
{
    "filename": "myfile.png",
    "path": "relative/path/to/myfile.png",
    "mediaType": "image/png"
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.png",
  "_location": "https://s3.us-west-1.amazonaws.com/mybucket/relative/path/to/myfile.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Update a file

This operation overrides the payload.

In order to ensure a client does not perform any changes to a file without having had seen the previous revision of the file, the last revision needs to be passed as a query parameter.

PUT /v1/files/{org_label}/{project_label}/{resource_id}?rev={previous_rev}

… where {previous_rev} is the last known revision number for the resource.

Example

Request
curl -XPUT -F "file=@/path/to/myfile2.png;type=image/png" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg?rev=1"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Tag a file

Links a file revision to a specific name.

Tagging a file is considered to be an update as well.

POST /v1/files/{org_label}/{project_label}/{file_id}/tags?rev={previous_rev}
  {
    "tag": "{name}",
    "rev": {rev}
  }

… where

  • {previous_rev}: is the last known revision number for the file.
  • {name}: String - label given to the file at specific revision.
  • {rev}: Number - the revision to link the provided {name}.

Example

Request
curl -XPOST -H "Content-Type: application/json" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/tags?rev=2" -d \
'{
  "tag": "mytag",
  "rev": 1
}'
Full source at GitHub
Payload
{
  "tag": "mytag",
  "rev": 1
}
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-10-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Deprecate a file

Locks the file, so no further operations can be performed.

Deprecating a file is considered to be an update as well.

DELETE /v1/files/{org_label}/{project_label}?rev={previous_rev}

… where {previous_rev} is the last known revision number for the file.

Example

Request
curl -XDELETE "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile/tags?rev=3"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-12-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Fetch a file (current version)

GET /v1/files/{org_label}/{project_label}/{file_id}

Example

Request (binary)
curl "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg"
Full source at GitHub
Request (metadata)
curl -H "Accept: application/json" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-12-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Fetch a resource (specific version)

GET /v1/files/{org_label}/{project_label}/{file_id}?rev={rev}

… where {rev} is the revision number of the file to be retrieved.

Example

Request (binary)
curl "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg?rev=4"
Full source at GitHub
Request (metadata)
curl -H "Accept: application/json" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg/rev=4"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "nxv:myfile",
  "@type": "File",
  "_bytes": 2670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile2.png",
  "_mediaType": "image/png",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-12-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

Fetch a resource (specific tag)

GET /v1/files/{org_label}/{project_label}/{file_id}?tag={tag}

… where {tag} is the tag of the file to be retrieved.

Example

Request (binary)
curl "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg?tag=mytag"
Full source at GitHub
Request (metadata)
curl -H "Accept: application/json" "https://nexus.example.com/v1/files/myorg/myproj/nxv:myfile.jpg/tag=mytag"
Full source at GitHub
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "@type": "File",
  "_bytes": 670,
  "_digest": {
    "_algorithm": "SHA-256",
    "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
  },
  "_filename": "myfile.jpg",
  "_mediaType": "image/jpeg",
  "_self": "https://nexus.example.com/v1/files/myorg/myproj/base:d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2019-01-28T12:15:33.238Z",
  "_createdBy": "https://nexus.example.com/v1/anonymous",
  "_updatedAt": "2019-01-28T12:15:33.238Z",
  "_updatedBy": "https://nexus.example.com/v1/anonymous"
}
Full source at GitHub

List files

GET /v1/files/{org_label}/{project_label}?from={from}&size={size}&deprecated={deprecated}&rev={rev}&type={type}&createdBy={createdBy}&updatedBy={updatedBy}

where…

  • {full_text_search_query}: String - can be provided to select only the files in the collection that have attribute values matching (containing) the provided token; when this field is provided the results will also include score values for each result
  • {from}: Number - is the parameter that describes the offset for the current query; defaults to 0
  • {size}: Number - is the parameter that limits the number of results; defaults to 20
  • {deprecated}: Boolean - can be used to filter the resulting files based on their deprecation status
  • {rev}: Number - can be used to filter the resulting files based on their revision value
  • {type}: Iri - can be used to filter the resulting files based on their @type value. This parameter can appear multiple times, filtering further the @type value.
  • {createdBy}: Iri - can be used to filter the resulting files based on their creator
  • {updatedBy}: Iri - can be used to filter the resulting files based on the person which performed the last update

Example

Request
curl "https://nexus.example.com/v1/files/myorg/myproj"
Full source at GitHub
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "_total": 2,
  "_results": [
    {
      "@id": "https://bluebrain.github.io/nexus/vocabulary/myfile",
      "@type": "https://bluebrain.github.io/nexus/vocabulary/File",
      "_bytes": 670,
      "_digest": {
        "_algorithm": "SHA-256",
        "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
      },
      "_filename": "myfile.jpg",
      "_mediaType": "image/jpeg",
      "_self": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fbluebrain.github.io%2Fnexus%2Fvocabulary%2Fmyfile",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
      "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2019-01-28T12:15:33.238Z",
      "_createdBy": "https://nexus.example.com/v1/anonymous",
      "_updatedAt": "2019-01-28T12:15:33.238Z",
      "_updatedBy": "https://nexus.example.com/v1/anonymous"
    },
    {
      "@id": "https://nexus.example.com/mybase/d8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
      "@type": "https://bluebrain.github.io/nexus/vocabulary/File",
      "_bytes": 2670,
      "_digest": {
        "_algorithm": "SHA-256",
        "_value": "25fc54fba0beec17a598b5a68420ded1595b2f76f0a0b7c6077792ece828bc2e"
      },
      "_filename": "myfile2.png",
      "_mediaType": "image/png",
      "_self": "https://nexus.example.com/v1/files/myorg/myproj/https%3A%2F%2Fnexus.example.com%2Fmybase%2Fd8848d4c-68f7-4ffd-952f-63a8cbcb86a9",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/file.json",
      "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
      "_rev": 1,
      "_deprecated": false,
      "_createdAt": "2019-01-28T12:15:33.238Z",
      "_createdBy": "https://nexus.example.com/v1/anonymous",
      "_updatedAt": "2019-12-28T12:15:33.238Z",
      "_updatedBy": "https://nexus.example.com/v1/anonymous"
    }
  ]
}
Full source at GitHub