API docs by Redocly

EvoNEST API (2.0.0)

Download OpenAPI specification:Download

Daniele Liprandi: daniele.liprandi@gmail.com URL: https://github.com/daniele-liprandi/EvoNEST-backbone License: GNU Affero General Public License v3.0

EvoNEST General Documentation

The EvoNEST User documentation and the EvoNEST Developer Docs are found here: https://daniele-liprandi.github.io/EvoNEST-backbone/

EvoNEST API Documentation

The EvoNEST API allows users to interact with the MongoDB databases generated in their NEST, plus it gives access to utility functions useful in ecological, evolutionary and biological research.

Features

  • Samples Management: Create, update, and retrieve biological samples with taxonomic information
  • Traits Measurement: Record and analyze trait measurements with statistical calculations
  • Experiments: Manage measurements, documents and raw data
  • File Storage: Upload and manage research files with metadata
  • User Management: Handle user accounts and permissions
  • Utilities: Geocoding, species image search, and data processing tools

Authentication

Most endpoints require proper authentication and database access permissions.

Data Format

All endpoints return JSON data unless otherwise specified. Dates are in ISO 8601 format.

Users

User account management and authentication

Retrieve all users

Get a list of all users in the system. When not in auth mode, filters users by database access based on the current user's permissions.

Authorizations:
bearerAuthsessionAuth
query Parameters
auth
boolean

Set to true to bypass database filtering (for authentication flows)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create, update, or modify a user

Handles multiple user operations based on the method field:

  • create: Create a new user account
  • update: Update an existing user's information
  • setfield: Update a specific field of a user
  • delete: Remove a user from the system
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
required
string
Value: "create"

Action to perform

name
required
string

User's full name

email
required
string <email>

User's email address

institution
string

User's affiliated institution

role
string
Enum: "admin" "researcher" "student" "viewer"

User's role in the system

databases
Array of strings

List of databases the user should have access to

Responses

Request samples

Content type
application/json
Example
{
  • "method": "create",
  • "name": "Dr. Jane Smith",
  • "email": "jane.smith@university.edu",
  • "institution": "University of Science",
  • "role": "researcher",
  • "databases": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "User updated successfully",
  • "id": "507f1f77bcf86cd799439011"
}

Get current user information

Retrieves the current authenticated user's profile information from the database

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "name": "John Doe",
  • "email": "john.doe@example.com",
  • "institution": "University of Science",
  • "role": "researcher",
  • "databases": [
    ],
  • "activeDatabase": "spiderdb",
  • "isActive": true,
  • "createdDate": "2024-01-15T10:30:00Z",
  • "recentChangeDate": "2024-03-15T10:30:00Z",
  • "logbook": [
    ],
  • "auth0id": "auth0|507f1f77bcf86cd799439011"
}

Update user information

Updates specific fields in the current authenticated user's profile

Authorizations:
sessionAuth
Request Body schema: application/json
method
required
string
Value: "setfield"

Update method

id
string

User ID to update

name
string

User's full name

email
string <email>

User's email address

institution
string

User's affiliated institution

role
string
Enum: "admin" "researcher" "student" "viewer"

User's role in the system

databases
Array of strings

List of databases the user should have access to

isActive
boolean

Whether the user account is active

field
required
string

Field name to update

required
string or number or boolean

New value for the field

Responses

Request samples

Content type
application/json
Example
{
  • "method": "setfield",
  • "field": "name",
  • "value": "Jane Doe"
}

Response samples

Content type
application/json
{
  • "message": "User updated successfully"
}

Check current user's role

Returns the current authenticated user's role information

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "isAdmin": true
}

Get user's database access information

Retrieve list of databases the user has access to and their currently active database

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "databases": [
    ],
  • "activeDatabase": "string"
}

Set active database for user

Switch the user's active database to a different one they have access to

Authorizations:
None
Request Body schema: application/json
database
required
string

Name of the database to set as active

Responses

Request samples

Content type
application/json
{
  • "database": "string"
}

List all API keys for authenticated user

Retrieve all API keys associated with the current user account, showing only key previews for security

Authorizations:
None

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate a new API key

Create a new API key for the authenticated user with specified name and expiration

Authorizations:
None
Request Body schema: application/json
name
string

Name/description for the API key

expiresInDays
number

Number of days until key expires (optional)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "expiresInDays": 0
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "apiKey": "string",
  • "keyInfo": { }
}

Revoke an API key

Delete/revoke an existing API key

Authorizations:
None
Request Body schema: application/json
keyId
string

ID or preview of the key to revoke

Responses

Request samples

Content type
application/json
{
  • "keyId": "string"
}

Get user authentication and profile status

Retrieves the current user's authentication status and database profile information. Used to determine if a user needs to complete their profile setup after authentication.

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
Example
{
  • "user": {
    },
  • "dbuser": {
    },
  • "needsIdentification": false
}

Samples

Biological sample management and taxonomic data

Retrieve all samples

Get a list of all samples in the database. Supports query parameters for filtering and pagination.

Authorizations:
bearerAuthsessionAuth
query Parameters
method
string
Value: "get-schema"

Special method to get sample schema instead of data

type
string
Enum: "animal" "silk" "other"

Filter samples by type

family
string

Filter samples by taxonomic family

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update samples

Create new samples, update existing ones, or perform bulk operations

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
string
Enum: "update" "setfield" "incrementfield"

Operation type

id
string

Sample ID for update operations

field
string

Field name to update

value
any

New value for the field

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Nephila clavipes #15",
  • "type": "animal",
  • "family": "Araneidae",
  • "genus": "Nephila",
  • "species": "clavipes"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "insertedId": "string"
}

Export samples data with API key authentication

Export all samples from a database using API key authentication. Supports various filtering and relationship inclusion options.

Authorizations:
None
query Parameters
database
required
string

Database name to export from

apiKey
string

API key for authentication (can also use Authorization header)

format
string
Default: "json"

Export format (only JSON supported)

type
string
Enum: "animal" "silk" "other"

Filter samples by type

includeRelated
boolean
Default: false

Include parent sample data chain

Responses

Response samples

Content type
application/json
[
  • { }
]

Traits

Trait measurements and statistical analysis

Retrieve trait measurements

Get a list of trait measurements with optional filtering by type and optional inclusion of sample features for enhanced data analysis.

Authorizations:
bearerAuthsessionAuth
query Parameters
includeSampleFeatures
boolean
Example: includeSampleFeatures=true

Include associated sample information in the response

type
string
Example: type=silk_diameter

Filter traits by specific type

id
string
Example: id=507f1f77bcf86cd799439011

Retrieve a specific trait by its ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create, update, or delete trait measurements

Handles multiple trait operations based on the method field:

  • create: Add a new trait measurement
  • update: Modify an existing trait measurement
  • delete: Remove a trait measurement
  • setfield: Update a specific field of a trait
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
required
string
Value: "create"

Action to perform

type
required
string

Type of trait measurement

sampleId
required
string

Reference to the sample

responsible
required
string

ID of the user responsible for this measurement

date
required
string <date>

Date when the measurement was taken

measurement
number

The measured value

unit
string

Unit of measurement

detail
string

Additional details about the measurement

equipment
string

Equipment used for measurement

nfibres
string

Number of fibers measured

listvals
Array of numbers

Individual measurement values

notes
string

Additional notes about the measurement

filesId
Array of strings

Associated file IDs

Responses

Request samples

Content type
application/json
{
  • "method": "create",
  • "type": "silk_diameter",
  • "sampleId": "507f1f77bcf86cd799439012",
  • "responsible": "507f1f77bcf86cd799439013",
  • "date": "2024-03-15",
  • "measurement": 2.5,
  • "unit": "μm",
  • "equipment": "SEM",
  • "nfibres": "1",
  • "detail": "major ampullate silk",
  • "notes": "Good quality sample"
}

Response samples

Content type
application/json
{
  • "message": "Trait created successfully",
  • "id": "507f1f77bcf86cd799439011"
}

Export traits data with API key authentication

Export all trait measurements from a database using API key authentication. Supports filtering and inclusion of sample features and related data.

Authorizations:
None
query Parameters
database
required
string

Database name to export from

apiKey
string

API key for authentication (can also use Authorization header)

format
string
Default: "json"

Export format (only JSON supported)

type
string

Filter traits by type

includeSampleFeatures
boolean
Default: false

Include associated sample information

includeRelated
boolean
Default: false

Include related sample chain data

Responses

Response samples

Content type
application/json
[
  • { }
]

Convert traits to their default units

Converts trait measurements to their default units based on SI prefix conversion. Can convert specific traits by ID or all traits in the database. Only converts traits where the current unit is compatible with the default unit (i.e., same base unit with different SI prefix).

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
traitIds
Array of strings

Optional array of trait IDs to convert. If not provided, converts all traits.

Responses

Request samples

Content type
application/json
{
  • "traitIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "totalTraits": 150,
  • "converted": 45,
  • "skipped": 105,
  • "details": [
    ]
}

Preview trait unit conversions without applying changes

Analyzes which traits would be converted and returns preview data without modifying the database. Shows the first 10 conversions that would be applied.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
traitIds
Array of strings

Optional array of trait IDs to preview. If not provided, previews all traits.

Responses

Request samples

Content type
application/json
{
  • "traitIds": [
    ]
}

Response samples

Content type
application/json
{
  • "totalTraits": 0,
  • "willConvert": 0,
  • "willSkip": 0,
  • "preview": [
    ]
}

Perform statistical analysis on trait data

Analyze trait measurements with statistical calculations (mean, stddev, min, max, median) grouped by various sample features

Authorizations:
None
Request Body schema: application/json
traitType
required
string

Type of trait to analyze (e.g., stressAtBreak, diameter, toughness)

groupBy
string
Default: "all"

Field to group results by (e.g., species, sex, sampleType)

filters
object

Optional filters to apply to the data

unitConversion
boolean
Default: true

Whether to apply unit conversions

Responses

Request samples

Content type
application/json
{
  • "traitType": "string",
  • "groupBy": "all",
  • "filters": { },
  • "unitConversion": true
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "processingTime": 0
}

Experiments

Experimental procedures and raw data management

Retrieve experiments

Get a list of experiments with optional inclusion of raw experimental data and filtering options.

Authorizations:
bearerAuthsessionAuth
query Parameters
includeRawData
boolean
Example: includeRawData=true

Include raw experimental data in the response

includeOriginalData
boolean

Include original (unprocessed) data instead of current data

type
string
Example: type=mechanical_test

Filter experiments by type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create, update, or delete experiments

Handles multiple experiment operations based on the method field:

  • create: Add a new experiment
  • update: Modify an existing experiment
  • delete: Remove an experiment
  • addRawData: Add raw data to an experiment
  • processData: Process raw experimental data
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
required
string
Value: "create"

Action to perform

name
required
string

Experiment name

type
required
string

Type of experiment

description
string

Detailed description of the experiment

responsible
required
string

ID of the user responsible for this experiment

date
string <date>

Experiment date

samples
Array of strings

List of sample IDs used in this experiment

equipment
string

Equipment used for the experiment

conditions
object

Environmental or experimental conditions

Responses

Request samples

Content type
application/json
{
  • "method": "create",
  • "name": "Silk tensile strength study",
  • "type": "mechanical_test",
  • "description": "Testing the tensile strength of spider silk",
  • "responsible": "507f1f77bcf86cd799439013",
  • "date": "2024-03-15",
  • "samples": [
    ],
  • "equipment": "Instron 5544"
}

Response samples

Content type
application/json
{
  • "message": "Experiment created successfully",
  • "id": "507f1f77bcf86cd799439011"
}

Export experiments data with API key authentication

Export all experiments from a database using API key authentication. Supports filtering and inclusion of raw data and related samples.

Authorizations:
None
query Parameters
database
required
string

Database name to export from

apiKey
string

API key for authentication (can also use Authorization header)

format
string
Default: "json"

Export format (only JSON supported)

type
string

Filter experiments by type

includeRawData
boolean
Default: false

Include raw experimental data

includeOriginalData
boolean
Default: false

Include original unprocessed data

includeRelated
boolean
Default: false

Include related sample data chain

Responses

Response samples

Content type
application/json
[
  • { }
]

Export tensile test experimental data

Export tensile test experiment data in JSON format with session-based authentication

Authorizations:
None
query Parameters
format
string
Default: "json"

Export format (only JSON supported)

type
string
Default: "tensile_test"

Experiment type filter

Responses

Response samples

Content type
application/json
[
  • { }
]

Files

File upload, storage, and metadata management

Retrieve all files

Get a list of all files stored in the system with their metadata.

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload files

Upload one or more files to the system. Files are stored with metadata and can be linked to specific entries.

Authorizations:
bearerAuthsessionAuth
Request Body schema: multipart/form-data
files
Array of strings <binary>

Files to upload

entryType
string

Type of entry to link files to

deferredLink
boolean

Whether to defer linking until later

mediaType
string

Expected media type

Responses

Response samples

Content type
application/json
{
  • "message": "Files uploaded successfully",
  • "fileIds": [
    ]
}

Link a file to an entry

Links a file to a specific entry (sample, trait, or experiment). If the file was temporary, it will be moved to the appropriate directory structure and marked as permanent. The entry's logbook will be updated with the linking action.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
fileId
required
string^[0-9a-fA-F]{24}$

MongoDB ObjectId of the file to link

entryType
required
string
Enum: "sample" "trait" "experiment"

Type of entry to link the file to

entryId
required
string^[0-9a-fA-F]{24}$

MongoDB ObjectId of the entry to link the file to

Responses

Request samples

Content type
application/json
Example
{
  • "fileId": "507f1f77bcf86cd799439011",
  • "entryType": "sample",
  • "entryId": "507f1f77bcf86cd799439012"
}

Response samples

Content type
application/json
{
  • "success": true
}

Download a file by ID

Downloads a file from the server using its database ID. The file metadata is retrieved from the database and the actual file is served from the file system.

Authorizations:
bearerAuthsessionAuth
query Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: id=507f1f77bcf86cd799439011

MongoDB ObjectId of the file to download

Responses

Response samples

Content type
application/json
{
  • "error": "File ID is required."
}

Utilities

Helper functions for geocoding, image search, and data processing

Search for species images in GBIF

Search the Global Biodiversity Information Facility (GBIF) database for images of species based on a query string.

Authorizations:
bearerAuthsessionAuth
query Parameters
query
required
string
Example: query=Araneus diadematus

Species name or search query

Responses

Response samples

Content type
application/json
{}

Reverse geocode coordinates to address

Converts latitude and longitude coordinates to a human-readable address using OpenStreetMap's Nominatim service

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
lat
required
number <float> [ -90 .. 90 ]

Latitude coordinate

lon
required
number <float> [ -180 .. 180 ]

Longitude coordinate

Responses

Request samples

Content type
application/json
{
  • "lat": 52.52,
  • "lon": 13.405
}

Response samples

Content type
application/json
{
  • "location": {
    }
}

Method not allowed

GET method is not supported for this endpoint

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Method not allowed"
}

Get system notifications

Retrieves all current system notifications from an external JSON source with intelligent caching and fallback mechanisms.

Caching Strategy:

  • Responses are cached for 2.5 minutes to improve performance
  • Fresh data is fetched from external source when cache expires
  • Cache is updated automatically on successful external fetch Fallback Strategy:
  1. External JSON source (currently hardcoded due to environment variable configuration issues)
  2. Cached data (even if expired) when external source fails
  3. Local notifications.json file as final fallback

Current Implementation Note:

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
Example

Fast response from in-memory cache

null

Generate labeled QR code image

Downloads a QR code image from a URL and adds text labels to the right side of the image

Authorizations:
bearerAuthsessionAuth
query Parameters
qrcodeurl
required
string <uri>
Example: qrcodeurl=https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=Sample

URL of the QR code image to modify

labelwidth
integer [ 100 .. 1000 ]
Default: 400
Example: labelwidth=400

Width of the label area in pixels

label1
string <= 50 characters
Example: label1=Sample ID: 001

First label text (truncated if longer than 12 characters)

label2
string <= 50 characters
Example: label2=Date: 2024-03-15

Second label text (truncated if longer than 12 characters)

label3
string <= 50 characters
Example: label3=Location: Lab A

Third label text (truncated if longer than 12 characters)

Responses

Response samples

Content type
application/json
{
  • "error": "Failed to process image"
}

Geocode location names to coordinates

Convert location names or addresses to latitude/longitude coordinates using OpenStreetMap Nominatim service.

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
location
required
string

Location name or address to geocode

Responses

Request samples

Content type
application/json
Example
{
  • "location": "Berlin, Germany"
}

Response samples

Content type
application/json
{
  • "coordinates": {
    }
}

Check API status

Simple health check endpoint for the taxonomic name checking service

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "message": "checkname API working"
}

Validate and correct taxonomic names

Validates and corrects scientific names using various taxonomic databases. Supports two methods:

  • correctName: Returns the corrected/standardized name
  • fullTaxaInfo: Returns complete taxonomic hierarchy information

Data sources:

  • WSC: World Spider Catalog (spider-specific)
  • GNames: Global Names Verifier (general taxa) - uses data sources 1, 12, 13 (Catalogue of Life, Encyclopedia of Life, GBIF)
  • auto: Tries WSC first, falls back to GNames
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
taxa
required
string

Scientific name to check or validate

method
string
Default: "correctName"
Enum: "correctName" "fullTaxaInfo"

Type of operation to perform

source
string
Default: "auto"
Enum: "auto" "WSC" "GNames"

Data source for name checking (WSC = World Spider Catalog, GNames = Global Names Verifier)

family
string

Optional family name to provide taxonomic context (used with GNames)

Responses

Request samples

Content type
application/json
Example
{
  • "taxa": "Araneus diadematus",
  • "method": "correctName",
  • "source": "auto"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": "Araneus diadematus",
  • "source": "WSC"
}

Settings

Get main settings

Retrieve the main settings configuration including ID generation and lab info

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update main settings

Update the main settings configuration

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
object
object

Responses

Request samples

Content type
application/json
{
  • "idGeneration": {
    },
  • "labInfo": {
    }
}

Sample

Retrieve a single sample

Get a single sample by name, ID, or other query parameters using JSON body

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
name
string

Filter by sample name (exact match)

id
string

Filter by sample ID

type
string
Enum: "animal" "silk" "subsample" "other"

Filter by sample type

Responses

Request samples

Content type
application/json
Example
{
  • "name": "MACN-Ar 47148",
  • "type": "animal"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "name": "Araneus diadematus #42",
  • "type": "animal",
  • "family": "Araneidae",
  • "genus": "Araneus",
  • "species": "diadematus",
  • "location": "Berlin, Germany",
  • "date": "2024-03-15",
  • "collector": "Dr. Smith"
}

Documentation

Get dynamically generated OpenAPI specification

This endpoint uses swagger-jsdoc to automatically scan API route files and generate OpenAPI spec from JSDoc comments

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{ }

Databases

Get available databases

Retrieve list of available databases that can be assigned to users

Authorizations:
bearerAuthsessionAuth

Responses

Response samples

Content type
application/json
{
  • "databases": [
    ]
}

Add a new database

Add a new database to the available databases list (admin only)

Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
database
string

Database name to add

Responses

Request samples

Content type
application/json
{
  • "database": "newproject"
}

Configuration

Retrieve configuration

Get all configuration types or a specific type

Authorizations:
bearerAuthsessionAuth
query Parameters
type
string
Enum: "sampletypes" "traittypes" "equipmenttypes" "samplesubtypes" "silkcategories" "siprefixes" "baseunits"

Specific configuration type to retrieve

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "type": "sampletypes",
  • "data": [
    ],
  • "version": 0,
  • "lastModified": "2019-08-24T14:15:22Z",
  • "modifiedBy": "string",
  • "isDefault": true
}

Create or update configuration

Handle configuration operations:

  • create: Create new configuration type
  • update: Update entire configuration type
  • additem: Add single item to configuration
  • updateitem: Update single item in configuration
  • deleteitem: Remove single item from configuration
  • seed: Initialize with default data
Authorizations:
bearerAuthsessionAuth
Request Body schema: application/json
One of
method
string
Enum: "create" "update" "additem" "updateitem" "deleteitem" "seed"
type
string
Enum: "sampletypes" "traittypes" "equipmenttypes" "samplesubtypes" "silkcategories" "siprefixes"
Array of objects (ConfigItem)
object (ConfigItem)
oldValue
string

For updateitem - the current value to update

Responses

Request samples

Content type
application/json
{
  • "method": "create",
  • "type": "sampletypes",
  • "data": [
    ],
  • "item": {
    },
  • "oldValue": "string"
}

Seed database with default configurations

Replace existing configurations with defaults or create them if they don't exist

Authorizations:
bearerAuthsessionAuth

Responses