REST API reference

Summary

The following document is a reference guide for all the REST APIs that InvenioRDM exposes.

Intended audience

This guide is intended for advanced users, and developers of InvenioRDM that have some experience with using REST APIs and are aware of the expected functionality a repository would be exposing.

Authentication

The only authentication method supported at the moment for REST API calls is by using Bearer tokens that you can generate at the "Applications" section of your user account's settings of your InvenioRDM instance. There are two ways to pass the tokens in your requests.

Authorization HTTP header (recommended)

curl -H "Authorization: Bearer API-TOKEN" https://127.0.0.1:5000/api/records

access_token HTTP query string parameter

curl https://127.0.0.1:5000/api/records?access_token=API-TOKEN

Scopes

Work in progress

The available scopes for generated token are subject to change when the access control mechanisms to records are finalized.

When you create your API token you can also specify scopes that control what kind of resources and actions you can access using your token.

Scope Description
user:email Allows access to the user's email address

General information

Timestamps

Timestamps are in UTC and formatted according to ISO 8601.

Pretty print JSON

If you are exploring the API via a browser, you can have the JSON formatted by adding prettyprint=1 in the query string.

Example request

GET /api/records?prettyprint=1 HTTP/1.1

Drafts

Used for interacting with unpublished or edited draft records.

Authentication required

All requests to the draft-related REST API endpoints require authentication.

Create a draft record

POST /api/records

Parameters

Name Type Location Description
access object body Access options for the record.
metadata object body Metadata of the record.

Request

POST /api/records HTTP/1.1
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public"
  },
  "metadata": {
    "resource_type": { "type": "image", "subtype": "image-photo" },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ]
  }
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Get a draft record

GET /api/records/{id}/draft

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/records/{id}/draft HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Update a draft record

PUT /api/records/{id}/draft

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
access object body Access options for the record.
metadata object body Metadata of the record.

Request

PUT /api/records/{id}/draft HTTP/1.1
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted"
  },
  "metadata": {
    "resource_type": { "type": "image", "subtype": "image-photo" },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ]
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Publish a draft record

POST /api/records/{id}/draft/actions/publish

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89

Request

POST /api/records/{id}/draft/actions/publish HTTP/1.1

Response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": true,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/records/{id}",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}",
    "files": "{scheme+hostname}/api/records/{id}/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Edit a published record (Create a draft record from a published record)

POST /api/records/{id}/draft

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89

Request

POST /api/records/{id}/draft HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Draft files

Used to manage a draft's files.

List a draft's files

GET /api/records/{id}/draft/files

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89

Request

GET /api/records/{id}/draft/files HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": true,
  "links": {
    "self": "/api/records/{id}/draft/files"
  },
  "entries": [],
  "default_preview": null,
  "order": []
}

Start draft file upload(s)

POST /api/records/{id}/draft/files

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
<top-level> array body Array of objects describing the file uploads to be initialized.
[].key string body Name of the file to be uploaded.

Request

POST /api/records/{id}/draft/files HTTP/1.1
Content-Type: application/json

[
  {"key": "figure.png"},
  {"key": "article.pdf"},
  {"key": "data.zip"}
]

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "enabled": true,
  "default_preview": null,
  "order": [],
  "entries": [
    {
      "key": "figure.png",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/figure.png/content",
        "self": "/api/records/{id}/draft/files/figure.png",
        "commit": "/api/records/{id}/draft/files/figure.png/commit"
      },
    },
        {
      "key": "article.pdf",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/article.pdf/content",
        "self": "/api/records/{id}/draft/files/article.pdf",
        "commit": "/api/records/{id}/draft/files/article.pdf/commit"
      },
    },
    {
      "key": "data.zip",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/data.zip/content",
        "self": "/api/records/{id}/draft/files/data.zip",
        "commit": "/api/records/{id}/draft/files/data.zip/commit"
      },
    }
  ],
  "links": {
    "self": "/api/records/{id}/draft/files"
  },
}

Upload a draft file's content

PUT /api/records/{id}/draft/files/{filename}/content

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
filename string path Name of the file.
content-type string header Should always be application/octet-stream.
content-length integer header Size of the content in bytes (optional).
<content> bytes body The raw bytes of the file content to be uploaded.

Request

PUT /api/records/{id}/draft/files/{filename}/content HTTP/1.1
Content-Type: application/octet-stream

<...file binary data...>

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:17:11.002624",
  "created": "2020-11-27 11:17:10.998919",
  "metadata": null,
    "status": "pending",
    "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Code sample

curl \
  --request PUT \
  --header "Content-Type: application/octet-stream" \
  https://127.0.0.1:5000//api/records/{id}/draft/files/{filename}/content \
  --upload-file /path/to/file

Complete a draft file upload

POST /api/records/{id}/draft/files/{filename}/commit

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
filename string path Name of the file.

Request

POST /api/records/{id}/draft/files/{filename}/commit HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:26:04.607831",
  "created": "2020-11-27 11:17:10.998919",
  "checksum": "md5:6ef4267f0e710357c895627e931f16cd",
  "mimetype": "image/png",
  "size": 89364.0,
  "status": "completed",
  "metadata": null,
  "file_id": "2151fa94-6dc3-4965-8df9-ec73ceb9175c",
  "version_id": "57ad8c66-b934-49c9-a46f-38bf5aa0374f",
  "bucket_id": "90b5b318-114a-4b87-bc9d-0d018b9363d3",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Get a draft file's metadata

GET /api/records/{id}/draft/files/{filename}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
filename string path Name of the file.

Request

GET /api/records/{id}/draft/files/{filename} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:26:04.607831",
  "created": "2020-11-27 11:17:10.998919",
  "checksum": "md5:6ef4267f0e710357c895627e931f16cd",
  "mimetype": "image/png",
  "size": 89364.0,
  "status": "completed",
  "metadata": null,
  "file_id": "2151fa94-6dc3-4965-8df9-ec73ceb9175c",
  "version_id": "57ad8c66-b934-49c9-a46f-38bf5aa0374f",
  "bucket_id": "90b5b318-114a-4b87-bc9d-0d018b9363d3",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Download a draft file

GET /api/records/{id}/draft/files/{filename}/content

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
filename string path Name of a file

Request

GET /api/records/{id}/draft/files/{filename}/content HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Disposition: inline
Content-Length: 76122
Content-MD5: 71449104d017a6056ac1a5fb58754975
Content-Type: image/pdf
Date: Thu, 26 Nov 2020 18:35:33 GMT
ETag: "md5:71449104d017a6056ac1a5fb58754975"
Last-Modified: Thu, 26 Nov 2020 14:30:06 GMT

<...file binary data...>

Delete a draft file

DELETE /api/records/{id}/draft/files/{filename}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
filename string path Name of the file.

Request

DELETE /api/records/{id}/draft/files/{filename} HTTP/1.1

Response

HTTP/1.1 204 No Content
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:26:04.607831",
  "created": "2020-11-27 11:17:10.998919",
  "checksum": "md5:6ef4267f0e710357c895627e931f16cd",
  "mimetype": "image/png",
  "size": 89364.0,
  "status": "completed",
  "metadata": null,
  "file_id": "2151fa94-6dc3-4965-8df9-ec73ceb9175c",
  "version_id": "57ad8c66-b934-49c9-a46f-38bf5aa0374f",
  "bucket_id": "90b5b318-114a-4b87-bc9d-0d018b9363d3",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Modify a draft's files options

Used for enabling/disabling files for drafts, setting the default previewed file, ordering files, etc.

PUT /api/records/{id}/draft/files

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89
enabled boolean body Set to false to disable files for the record.
default_preview string body Filename of the file to be previewed by default on the published record.

Request

PUT /api/records/{id}/draft/files HTTP/1.1
Content-Type: application/json

{
  "enabled": true,
  "default_preview": "article.pdf",
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": true,
  "default_preview": "article.pdf",
  "order": [],
  "entries": [
    {
      "key": "figure.png",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/figure.png/content",
        "self": "/api/records/{id}/draft/files/figure.png",
        "commit": "/api/records/{id}/draft/files/figure.png/commit"
      },
    },
        {
      "key": "article.pdf",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/article.pdf/content",
        "self": "/api/records/{id}/draft/files/article.pdf",
        "commit": "/api/records/{id}/draft/files/article.pdf/commit"
      },
    }
  ],
  "links": {
    "self": "/api/records/{id}/draft/files"
  },
}

Records

Used for interacting with published records.

Get a record

GET /api/records/{id}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/records/{id} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": true,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/records/{id}",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}",
    "files": "{scheme+hostname}/api/records/{id}/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Search records

Parameters

Name Type Location Description
q string query Search query used to filter results based on ElasticSearch's query string syntax.
sort string query Sort search results.
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
allversions boolean query Specify if all versions should be included.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/records HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "aggregations": {...},
  "hits": {...},
  "links": {...},
  "sortBy": ...,
}

Each hit looks like a record above.

Record files

List a record's files

GET /api/records/{id}/files

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
accept string header - application/json (default)

Request

GET /api/records/{id}/files HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": true,
  "default_preview": "article.pdf",
  "order": [],
  "entries": [
    {
      "key": "article.pdf",
      "created": "2020-11-26 14:30:53.911912",
            "updated": "2020-11-26 14:30:53.920544",
      "checksum": "md5:71449104d017a6056ac1a5fb58754975",
      "mimetype": "application/pdf",
      "size": 76122,
      "status": "completed",
      "metadata": {...},
      "file_id": "...",
      "version_id": "...",
      "bucket_id": "...",
      "storage_class": "S",
      "links": {
        "content": "/api/records/{id}/files/article.pdf/content",
        "self": "/api/records/{id}/files/article.pdf"
      }
    }
  ]
  "links": {...},
}

Get a record file's metadata

GET /api/records/{id}/files/{filename}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
filename string path Name of a file
accept string header - application/json (default)

Request

GET /api/records/{id}/files/{filename} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "created": "2020-11-26 14:30:53.911912",
  "updated": "2020-11-26 14:30:53.920544",
  "checksum": "md5:71449104d017a6056ac1a5fb58754975",
  "mimetype": "application/pdf",
  "size": 76122,
  "status": "completed",
  "metadata": {...},
  "file_id": "...",
  "version_id": "...",
  "bucket_id": "...",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/files/{filename}/content",
    "self": "/api/records/{id}/files/{filename}"
  }
}

Download a record file

GET /api/records/{id}/files/{filename}/content

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
filename string path Name of a file

Request

GET /api/records/{id}/files/{filename}/content HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Disposition: inline
Content-Length: 76122
Content-MD5: 71449104d017a6056ac1a5fb58754975
Content-Type: image/pdf
Date: Thu, 26 Nov 2020 18:35:33 GMT
ETag: "md5:71449104d017a6056ac1a5fb58754975"
Last-Modified: Thu, 26 Nov 2020 14:30:06 GMT

<...file binary data...>

Versions

Create a new version

POST /api/records/{id}/versions

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. 4d0ns-ntd89

Request

POST /api/records/{id}/versions HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{new-id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "An Updated Romans story",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 2,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Notice that a new draft is returned with publication_date and version removed (as those are typically replaced in a new version). The versions.index is also incremented. The {parent-id} connects the different versions together.

Use (Publish a draft record)[#publish-a-draft-record] to publish it.

POST /api/records

Parameters

Name Type Location Description
access object body Access options for the record.
metadata object body Metadata of the record.

Request

POST /api/records HTTP/1.1
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public"
  },
  "metadata": {
    "resource_type": { "type": "image", "subtype": "image-photo" },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ]
  }
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Get latest version

Given a record, it returns its latest version.

GET /api/records/{id}/versions/latest

Parameters

Name Type Location Description
id string path Identifier of a record, e.g. cbc2k-q9x58
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/records/{id}/versions/latest HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "id": "{latest-version-id}",
  "is_published": true,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/records/{id}",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}",
    "files": "{scheme+hostname}/api/records/{id}/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links",
  },
  "metadata": {
    "resource_type": { "subtype": "image-photo", "type": "image" },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "identifiers": [
              {"scheme": "ror", "identifier": "03yrm5c26"}
            ],
            "name": "Entity One"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 2,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Access links are URLs that can be shared with others to give them access and permissions to a record/draft.

POST /api/records/{id}/access/links

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
expires_at string body Date time string. When the link expires.
permission string body Required. Action that can be undertaken with the link.

Request

POST /api/records/{id}/access/links HTTP/1.1
Content-Type: application/json

{
  "permission": "read"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "permission": "read",
  "created_at": "2021-03-25T21:06:29.563235",
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjNkMzMyMGVhLTA3NTUtNGQ5My1hNzZlLWUyZjJmYzY1NWQyYSIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzZhYTk3OTczMzgwMjkyNTJiM2MwZDBjNjliMTVkYSJ9.dBqk7YzIZ7kwG4oijNgH1VU-cjQmBiQlMQKMoB2y-YjVWmgnZetFAESsqRP6VpGTtaKdftrtob1PVZJF4YGpfg",
  "id": "3d3320ea-0755-4d93-a76e-e2f2fc655d2a",
  "expires_at": null
}

GET /api/records/{id}/access/links/{link-id}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
link-id string path Identifier of the link, e.g. 3d3320ea-0755-4d93-a76e-e2f2fc655d2a
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/records/{id}/access/links/{link-id} HTTP/1.1
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "permission": "read",
  "created_at": "2021-03-25T21:06:29.563235",
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjNkMzMyMGVhLTA3NTUtNGQ5My1hNzZlLWUyZjJmYzY1NWQyYSIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzZhYTk3OTczMzgwMjkyNTJiM2MwZDBjNjliMTVkYSJ9.dBqk7YzIZ7kwG4oijNgH1VU-cjQmBiQlMQKMoB2y-YjVWmgnZetFAESsqRP6VpGTtaKdftrtob1PVZJF4YGpfg",
  "id": "3d3320ea-0755-4d93-a76e-e2f2fc655d2a",
  "expires_at": null
}

PATCH /api/records/{id}/access/links/{link-id}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
link-id string path Identifier of the link, e.g. 3d3320ea-0755-4d93-a76e-e2f2fc655d2a
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
expires_at string body Date time string. When the link expires.
permission string body Required. Action that can be undertaken with the link.

Request

PATCH /api/records/{id}/access/links/{link-id} HTTP/1.1
Content-Type: application/json

{
  "permission": "manage",
  "expires_at": "2121-03-25T21:06:29.563235"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "permission": "manage",
  "created_at": "2021-03-25T21:06:29.563235",
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjNkMzMyMGVhLTA3NTUtNGQ5My1hNzZlLWUyZjJmYzY1NWQyYSIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzZhYTk3OTczMzgwMjkyNTJiM2MwZDBjNjliMTVkYSJ9.dBqk7YzIZ7kwG4oijNgH1VU-cjQmBiQlMQKMoB2y-YjVWmgnZetFAESsqRP6VpGTtaKdftrtob1PVZJF4YGpfg",
  "id": "3d3320ea-0755-4d93-a76e-e2f2fc655d2a",
  "expires_at": "2121-03-25T21:06:29.563235"
}

DELETE /api/records/{id}/access/links/{link-id}

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
link-id string path Identifier of the link, e.g. 3d3320ea-0755-4d93-a76e-e2f2fc655d2a
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

DELETE /api/records/{id}/access/links/{link-id} HTTP/1.1
Content-Type: application/json

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

GET /api/records/{id}/access/links

Parameters

Name Type Location Description
id string path Identifier of the record, e.g. cbc2k-q9x58
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/records/{id}/access/links HTTP/1.1
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hits": {
    "hits": [
      {
        "permission": "read",
        "id": "140f69c9-a8a5-41d4-8ae2-3dfbfe0e2796",
        "created_at": "2021-03-25T21:48:03.289198",
        "expires_at": null,
        "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjE0MGY2OWM5LWE4YTUtNDFkNC04YWUyLTNkZmJmZTBlMjc5NiIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzE3MmY4MTNkYzhkNGJjZDAwOWFlOTlhOWM3NjU1MSJ9.1O9MwTmt_nfvsCm4qvlkUH0Rpe5bK3hT422A879DJSblOCONsNxPe_feNHrgTV3s6ZA6t6vLziXjhAwgKjHhIQ"
      }
    ],
    "total": 1
  }
}

User Records

List your draft or published records

GET /api/user/records

Parameters

Name Type Location Description
q string query Search query used to filter results based on ElasticSearch's query string syntax.
sort string query Sort search results.
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
allversions boolean query Specify if all versions should be included.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

GET /api/user/records HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "aggregations": {...},
  "hits": {...},
  "links": {...},
  "sortBy": ...,
}

Vocabularies

Used for accessing vocabulary records. Currently the following vocabularies are supported:

  • Languages (ISO 639-3 language codes)
  • Licenses (SPDX licenses)

Search vocabularies

Parameters

Name Type Location Description
type string path Vocabulary (one of languages or licenses)
q string query Search query used to filter results based on ElasticSearch's query string syntax.
tags string query Filter results to the tag
sort string query Sort search results.
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Specifically for the application/vnd.inveniordm.v1+json format:

Name Type Location Description
ln string query Locale used to localize the title and description (e.g. en or en_US)
accept-language string header Locale used to localize the title and description (e.g. en or en_US)

The API uses a locale matching algorithm, that will do it's best effort to translate the vocabulary record's title and description.

Request

GET /api/vocabularies/{type} HTTP/1.1

Response

For all vocabularies:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "aggregations": {...},
  "hits": {...},
  "links": {...},
  "sortBy": ...,
}

Each hit looks like a vocabulary record below.

Get a vocabulary record

GET /api/vocabularies/{type}/{id}

Parameters

Name Type Location Description
type string path Vocabulary (one of languages or licenses)
id string path Identifier of the record, e.g. eng
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
accept-language string header For- application/json (default)
- application/vnd.inveniordm.v1+json

Specifically for the application/vnd.inveniordm.v1+json format:

Name Type Location Description
ln string query Locale used to localize the title and description (e.g. en or en_US)
accept-language string header Locale used to localize the title and description (e.g. en or en_US)

The API uses a locale matching algorithm, that will do it's best effort to translate the vocabulary record's title and description.

Request

GET /api/vocabularies/{type}/{id} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{

  "id": "{id}",
  "type": "{type}",
  "created": "2020-11-26T19:20:39",
  "updated": "2020-11-26T19:20:39",
  "revision_id": 1,
  "title": {
    "en": "..."
  },
  "description": {
    "en": "..."
  },
  "icon": "...",
  "props": { ... },
  "tags": [...],
  "links": { ... }
}