REST API Guide

Reference and tutorials for performing API calls and automating workflows.

Search Records

The BERD@NFDI Data Portal provides a powerful search API to query published records. Search requests are unauthenticated and support filtering, sorting, and pagination.

Basic Search

Perform a simple text search across all records:

curl -X GET "https://berd-platform.de/api/records?q=economics"

Filter by Resource Type

Search for specific resource types using the resource_type.id field:

curl -X GET "https://berd-platform.de/api/records?q=metadata.resource_type.id:dataset-open"

Available resource types include:

• dataset-open
• dataset-funded
• dataset-long-term
• publication-article
• publication-conferencepaper
• text-collection-long-term
• text-long-term

Retrieve a Specific Record

Get detailed information about a specific record using its ID:

curl -X GET "https://berd-platform.de/api/records/$RECORD_ID"

Upload and Submit a Record

1. Create a Draft Record

To upload a dataset (or other resource type) to the BERD@NFDI Data Portal via the API, you need to create a record, that describes your submission just as you would via the deposit form. The metadata field of the payload you send needs to comply to the InvenioRDM metadata schema. Additionally, you may include BERD-specific custom fields.

Note that the resource_type must be one of:

• dataset-open
• dataset-funded
• dataset-long-term
• publication-article
• publication-conferencepaper
• text-collection-long-term
• text-long-term

curl -X POST "https://berd-platform.de/api/records" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "files": {
    "enabled": true
  },
  "metadata": {
    "title": "My New Record",
    "description": "This is a description of my record"
  },
  "access": {
    "record": "public",
    "files": "public"
  }
}'

Save the id of the newly created record from the response. You'll need it as $RECORD_ID for the next steps.

Alternatively, you may send the metadata from a JSON file:

curl -X POST "https://berd-platform.de/api/records" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @path/to/your/local/record_metadata.json

2. Upload a File

Uploading a file is a two-step process. It requires you to:

Initialize the File Upload

curl -X PUT "https://berd-platform.de/api/records/$RECORD_ID/draft/files" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '[{"key": "data.csv"}]'

Upload the File Contents

curl -X PUT "https://berd-platform.de/api/records/$RECORD_ID/draft/files/data.csv/content" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @path/to/your/local/file/data.csv

3. Find the Community

In the BERD@NFDI Data Portal each resource type is associated with a specific community. On manual submissions via the deposit form, this step is happening behind the scenes. When submitting records via the API, you need the community UUID to submit your record to the right community.

Community Mapping

To retrieve the community UUID, use the following command with the appropriate community slug:

curl -X GET "https://berd-platform.de/api/communities?q=opendata"

Take the id field from the response and use it in your record submission as $COMMUNITY_ID.

4. Create a Review Request

Submitted records are reviewed by community curators to ensure metadata quality and completeness.

curl -X PUT "https://berd-platform.de/api/records/$RECORD_ID/draft/review" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "receiver": {
      "community": "$COMMUNITY_ID"
    }, 
    "type": "community-submission"
  }'

5. Submit the Review

curl -X POST "https://berd-platform.de/api/records/$RECORD_ID/draft/actions/submit-review" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "content": "Thank you in advance for the review.",
      "format": "html"
    }
  }'

From the response, extract the request UUID. You'll need this for the acceptance step.

Review Request

After users have uploaded a record and submitted a review request, it needs to undergo a review by the curators of the respective community. The following steps describe how the receiver of a review request, or a community curator can act on such requests.

Comment on a Review Request

Add comments to provide feedback or request changes before accepting or declining the review request.

curl -X POST "https://berd-platform.de/api/requests/$REQUEST_ID/comments" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "payload": {
    "content": "Please update the metadata description.",
    "format": "html"
  }
}'

Accept the Review Request

curl -X POST "https://berd-platform.de/api/requests/$REQUEST_ID/actions/accept" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "payload": {
    "content": "Record accepted!",
    "format": "html"
  }
}'

Decline the Review Request

curl -X POST "https://berd-platform.de/api/requests/$REQUEST_ID/actions/decline" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "payload": {
    "content": "Record declined!",
    "format": "html"
  }
}'