Link copied to your clipboard
Failed to copy link to your clipboard

REST API endpoints for SONAR

  • api
  • developer
Last updated: 17-09-2026

Documents

List

GET /api/documents/

Get the list of documents (search).

  • The search syntax is documented in detail on the Elasticsearch website: Query String Syntax. See also some examples below.
  • The SONAR documentation provides a list of the document's fields with their JSON code.
  • These fields are indexed in the Elasticsearch engine according to a configuration defined in a mapping (available on Github). It defines what exactly is accessible in the ElasticSearch indexes.

For more info on search queries and a list of examples, see the search section.

Create

POST /api/documents/

Create a new document. Here's an example of the data to send:

{
    "title": [
        {
            "mainTitle": [
                {
                    "language": "eng",
                    "value": "Title of the document"
                }
            ],
            "type": "bf:Title"
        }
    ],
    "language": [
        {
            "type": "bf:Language",
            "value": "eng"
        }
    ],
    "organisation": [
        {
            "$ref": "https://sonar.ch/api/organisations/rero"
        }
    ],
    "provisionActivity": [
        {
            "type": "bf:Publication",
            "startDate": "2019"
        }
    ],
    "documentType": "coar:c_2f33"
}

Read

GET /api/documents/[ID]

Get a specific document.

Update

PUT /api/documents/[ID]

Update an existing document. Here's an example of the data to send:

{
    "_bucket": "9f8f303f-54fd-4d1a-82e9-fdf9b8ce1801",
    "_oai": {
        "id": "oai:sonar.ch:9",
        "sets": [
            "rero"
        ],
        "updated": "2021-02-03T08:37:33.744426+00:00"
    },
    "documentType": "coar:c_2f33",
    "language": [
        {
            "type": "bf:Language",
            "value": "eng"
        }
    ],
    "organisation": [
        {
            "$ref": "https://sonar.ch/api/organisations/rero"
        }
    ],
    "permalink": "https://localhost:5000/global/documents/9",
    "permissions": {
        "delete": true,
        "read": true,
        "update": true
    },
    "pid": "9",
    "provisionActivity": [
        {
            "startDate": "2019",
            "text": "2019",
            "type": "bf:Publication"
        }
    ],
    "title": [
        {
            "mainTitle": [
                {
                    "language": "eng",
                    "value": "Title of the document"
                }
            ],
            "type": "bf:Title"
        }
    ]
}

Delete

DELETE /api/documents/[ID]

Remove an existing document.

Organisations

List

GET /api/organisations/

Get the list of organisations.

Create

POST /api/organisations/

Create a new organisation. Here's an example of the data to send:

{
    "code": "org",
    "name": "Organisation",
    "isShared": true,
    "description": [
        {
            "language": "eng",
            "value": "Description of the organisation"
        }
    ],
    "isDedicated": true
}

Read

GET /api/organisations/[ID]

Get a specific organisation.

Update

PUT /api/organisations/[ID]

Update an existing organisation. Here's an example of the data to send:

{
    "_bucket": "e0f02af0-d18d-4a9c-a676-cc92a9cfcd3d",
    "code": "org",
    "name": "Organisation",
    "pid": "org",
    "isShared": true,
    "description": [
        {
            "language": "eng",
            "value": "Description of the organisation"
        }
    ],
    "isDedicated": true
}

Delete

DELETE /api/organisations/[ID]

Remove an existing organisation.

Users

List

GET /api/users/

Get the list of users.

Create

POST /api/users/

Create a new user. Here's an example of the data to send:

{
    "organisation": {
        "$ref": "https://sonar.ch/api/organisations/rero"
    },
    "role": "admin",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@rero.ch",
    "phone": "+4127123456",
    "birth_date": "1980-01-01",
    "street": "Av. de la Gare 45",
    "postal_code": "1920",
    "city": "Martigny"
}

Read

GET /api/users/[ID]

Get a specific user.

Update

PUT /api/users/[ID]

Update an existing user. Here's an example of the data to send:

{
    "birth_date": "1980-01-01",
    "city": "Martigny",
    "email": "john.doe@rero.ch",
    "first_name": "John",
    "last_name": "Doe",
    "organisation": {
        "$ref": "https://sonar.ch/api/organisations/rero"
    },
    "phone": "+4127123456",
    "pid": "11",
    "postal_code": "1920",
    "role": "admin",
    "street": "Av. de la Gare 45"
}

Delete

DELETE /api/users/[ID]

Remove an existing user.

Projects

List

GET /api/projects/

Get the list of projects.

Create

POST /api/projects/

Create a new project. Here's an example of the data to send:

{
    "organisation": {
        "$ref": "https://sonar.ch/api/organisations/rero"
    },
    "name": "Project",
    "description": "Description",
    "startDate": "2021-01-01",
    "endDate": "2022-01-01",
    "funding_organisations": [
        {
            "agent": {
                "preferred_name": "RERO"
            },
            "identifiedBy": {
                "type": "bf:Identifier",
                "value": "1111"
            }
        }
    ],
    "identifiedBy": {
        "type": "bf:Identifier",
        "value": "2222"
    },
    "investigators": [
        {
            "agent": {
                "preferred_name": "John Doe"
            },
            "role": [
                "investigator"
            ],
            "identifiedBy": {
                "type": "bf:Identifier",
                "value": "3333"
            },
            "affiliation": "RERO"
        }
    ]
}

Read

GET /api/projects/[ID]

Get a specific project.

Update

PUT /api/projects/[ID]

Update an existing project. Here's an example of the data to send:

{
    "description": "Description",
    "endDate": "2022-01-01",
    "funding_organisations": [
        {
            "agent": {
                "preferred_name": "RERO"
            },
            "identifiedBy": {
                "type": "bf:Identifier",
                "value": "1111"
            }
        }
    ],
    "identifiedBy": {
        "type": "bf:Identifier",
        "value": "2222"
    },
    "investigators": [
        {
            "affiliation": "RERO",
            "agent": {
                "preferred_name": "John Doe"
            },
            "identifiedBy": {
                "type": "bf:Identifier",
                "value": "3333"
            },
            "role": [
                "investigator"
            ]
        }
    ],
    "name": "Project",
    "organisation": {
        "$ref": "https://sonar.ch/api/organisations/rero"
    },
    "pid": "12",
    "startDate": "2021-01-01",
    "user": {
        "$ref": "https://sonar.ch/api/users/1"
    }
}

Delete

DELETE /api/projects/[ID]

Remove an existing project.

Deposits

List

GET /api/deposits/

Get the list of deposits.

Create

POST /api/deposits/

Create a new deposit. Here's an example of the data to send:

{
    "user": {
        "$ref": "https://sonar.ch/api/users/1"
    },
    "step": "metadata",
    "status": "in_progress"
}

Read

GET /api/deposits/[ID]

Get a specific deposit.

Update

PUT /api/deposits/[ID]

Update an existing deposit. Here's an example of the data to send:

{
    "pid": "13",
    "status": "in_progress",
    "step": "contributors",
    "user": {
        "$ref": "https://sonar.ch/api/users/1"
    },
    "metadata": {
        "identifiedBy": [
            {
                "type": "bf:Local",
                "value": "1111",
                "source": "RERO"
            }
        ],
        "specificCollections": [
            "Collection 1"
        ],
        "abstracts": [
            {
                "language": "eng",
                "abstract": "Document abstract"
            }
        ],
        "subjects": [
            {
                "subjects": [
                    "Subject 1",
                    "Subject 2"
                ],
                "language": "eng"
            }
        ],
        "documentType": "coar:c_2f33",
        "title": "Title of the document",
        "language": "eng",
        "publicationPlace": "Publication place",
        "publisher": "Publisher",
        "documentDate": "2020",
        "classification": "621"
    }
}

Delete

DELETE /api/deposits/[ID]

Remove an existing deposit.

List files

GET /api/deposits/[ID]/custom-files

Get the list of files associated with deposit.

Add file

POST /api/deposits/[ID]/custom-files?key=[FILE_NAME]&type=main|additional

Add a file to a deposit. The content of the file is put in the body.

Update file metadata

PUT /api/deposits/[ID]/custom-files/[FILE_NAME]

Update file metadata. Here's an example of the data to send:

{
    "label": "306655",
    "embargo": true,
    "embargoDate": "2021-02-10",
    "exceptInOrganisation": true
}

Collections

Collections exist for dedicated organisations only. Reading is open to any authenticated user of the organisation; creating, updating and deleting require the administrator role.

List

GET /api/collections/

Get the list of collections.

Create

POST /api/collections/

Create a new collection. Only name is required.

{
    "name": [
        {
            "language": "eng",
            "value": "Name of the collection"
        }
    ],
    "description": [
        {
            "language": "eng",
            "value": "Description shown on the collection landing page"
        }
    ],
    "organisation": {
        "$ref": "https://sonar.ch/api/organisations/rero"
    }
}

Read

GET /api/collections/[ID]

Get a specific collection.

Update

PUT /api/collections/[ID]

Update an existing collection. Send the whole record, including its pid.

Delete

DELETE /api/collections/[ID]

Remove an existing collection.

Subdivisions

Subdivisions exist for dedicated organisations only. Reading is open to any authenticated user of the organisation; creating, updating and deleting require the administrator role.

List

GET /api/subdivisions/

Get the list of subdivisions.

Create

POST /api/subdivisions/

Create a new subdivision. Only name is required.

{
    "name": [
        {
            "language": "eng",
            "value": "Faculty of Science"
        }
    ],
    "organisation": {
        "$ref": "https://sonar.ch/api/organisations/rero"
    }
}

Read

GET /api/subdivisions/[ID]

Get a specific subdivision.

Update

PUT /api/subdivisions/[ID]

Update an existing subdivision. Send the whole record, including its pid.

Delete

DELETE /api/subdivisions/[ID]

Remove an existing subdivision. The call fails while the subdivision is still assigned to a user, a document or a deposit.

Files

Endpoint to manage files for resources:

  • Deposits
  • Documents
  • Organisations

List

GET /api/[documents|deposits|organisations]/[ID]/files

List files associated with the resource. When passing parameter ?versions, all the files versions are returned.

Add

PUT /api/[documents|deposits|organisations]/[ID]/files/[FILE_NAME]

Add a file to the resource. The content of the file is put in the body. If the file already exists, a new version will be created.

Read

GET /api/[documents|deposits|organisations]/[ID]/files/[FILE_NAME]

Get a specific file. Pass an additional parameter ?versionId=[VERSION_ID] to get a specific version of the file.

Delete

DELETE /api/[documents|deposits|organisations]/[ID]/files/[FILE_NAME]

Delete the last version of a file. This does a soft delete, the file can be retrieved. By passing an additional parameter ?versionId=[VERSION_ID], a specific version can be deleted. This will do a hard delete, the file is erased from the disk.

Subdivisions | OAI-PMH service