apidoc/v2/openapi.yaml
openapi: 3.0.3
info:
title: eLabFTW REST API v2 Documentation
description: |
This document describes all available endpoints and methods for eLabFTW's API version 2.
version: 2.0.0
servers:
- url: https://elab.local:3148/api/v2
description: Local dev server
- url: https://eln.example.org/api/v2
description: Example base URL
components:
securitySchemes:
token:
type: apiKey
name: Authorization
in: header
schemas:
apikey:
type: object
properties:
id:
type: integer
name:
type: string
created_at:
type: string
last_used_at:
type: string
hash:
type: string
can_write:
type: integer
team:
type: integer
team_name:
type: string
comment:
type: object
properties:
id:
type: integer
created_at:
type: string
item_id:
type: integer
comment:
type: string
userid:
type: integer
modified_at:
type: string
fullname:
type: string
firstname:
type: string
lastname:
type: string
orcid:
type: string
config:
type: object
properties:
admins_create_users:
type: string
admins_create_users_remote_dir:
type: string
admin_validate:
type: string
announcement:
description: This text will be shown on every page, including login page.
type: string
anon_users:
type: string
autologout_time:
type: string
blox_anon:
type: string
blox_enabled:
type: string
cookie_validity_time:
type: integer
debug:
type: string
email_domain:
type: string
extauth_email:
type: string
extauth_firstname:
type: string
extauth_lastname:
type: string
extauth_remote_user:
type: string
extauth_teams:
type: string
lang:
type: string
ldap_base_dn:
type: string
ldap_search_attr:
type: string
ldap_email:
type: string
ldap_firstname:
type: string
ldap_host:
type: string
ldap_lastname:
type: string
ldap_password:
type: string
ldap_port:
type: string
ldap_team:
type: string
ldap_toggle:
type: string
ldap_use_tls:
type: string
ldap_username:
type: string
local_login:
type: string
local_register:
type: string
login_announcement:
description: This text will only be shown on the login page.
type: string
login_tries:
type: string
logout_url:
type: string
mail_from:
type: string
max_revisions:
type: string
min_days_revisions:
type: string
min_delta_revisions:
description: Minimum number of characters changed required to trigger a revision save.
type: string
onboarding_email_active:
enum: [0, 1]
type: string
onboarding_email_admins_body:
type: string
onboarding_email_admins_subject:
type: string
onboarding_email_body:
type: string
onboarding_email_different_for_admins:
enum: [0, 1]
type: string
onboarding_email_subject:
type: string
open_science:
type: string
open_team:
type: string
privacy_policy:
type: string
proxy:
type: string
remote_dir_config:
type: string
remote_dir_service:
type: string
s3_bucket_name:
type: string
s3_endpoint:
type: string
s3_path_prefix:
type: string
s3_region:
type: string
s3_verify_cert:
type: string
saml_acs_binding:
type: string
saml_allowrepeatattributename:
type: string
saml_authnrequestssigned:
type: string
saml_baseurl:
type: string
saml_debug:
type: string
saml_entityid:
type: string
saml_logoutrequestsigned:
type: string
saml_logoutresponsesigned:
type: string
saml_lowercaseurlencoding:
type: string
saml_nameidencrypted:
type: string
saml_nameidformat:
type: string
saml_privatekey:
type: string
saml_relaxdestinationvalidation:
type: string
saml_signmetadata:
type: string
saml_slo_binding:
type: string
saml_strict:
type: string
saml_sync_teams:
type: string
saml_team_create:
type: string
saml_team_default:
type: string
saml_toggle:
type: string
saml_user_default:
type: string
saml_wantassertionsencrypted:
type: string
saml_wantassertionssigned:
type: string
saml_wantmessagessigned:
type: string
saml_wantnameid:
type: string
saml_wantnameidencrypted:
type: string
saml_wantxmlvalidation:
type: string
saml_x509:
type: string
saml_x509_new:
type: string
schema:
type: string
smtp_address:
type: string
smtp_encryption:
type: string
smtp_password:
type: string
smtp_port:
type: string
smtp_username:
type: string
support_url:
type: string
ts_authority:
type: string
ts_cert:
type: string
ts_hash:
type: string
ts_limit:
type: string
ts_login:
type: string
ts_password:
type: string
ts_url:
type: string
uploads_storage:
type: string
entity:
type: object
properties:
access_key:
type: string
nullable: true
body:
type: string
nullable: true
body_html:
type: string
nullable: true
canread:
type: string
description: JSON string for read permissions.
canwrite:
type: string
description: JSON string for write permissions.
category:
type: integer
nullable: true
category_color:
type: string
nullable: true
category_title:
type: string
nullable: true
comments:
type: array
items:
$ref: '#/components/schemas/comment'
content_type:
type: integer
description: How the body is stored. 1 for HTML, 2 for Markdown. If you plan on creating an entity with markdown, make sure to set it to 2.
created_at:
type: string
custom_id:
type: integer
date:
type: string
elabid:
type: string
experiments_links:
type: array
items:
$ref: '#/components/schemas/link'
firstname:
type: string
fullname:
type: string
has_attachement:
type: integer
has_comment:
type: integer
id:
type: integer
items_links:
type: array
items:
$ref: '#/components/schemas/link'
lastchangeby:
type: integer
lastname:
type: string
locked:
type: integer
lockedby:
type: integer
nullable: true
locked_at:
type: string
nullable: true
metadata:
type: string
nullable: true
modified_at:
type: string
next_step:
type: string
nullable: true
orcid:
type: string
nullable: true
page:
type: string
rating:
type: integer
recent_comment:
type: string
nullable: true
related_experiments_links:
type: array
items:
$ref: '#/components/schemas/link'
related_items_links:
type: array
items:
$ref: '#/components/schemas/link'
sharelink:
type: string
state:
type: integer
status:
type: integer
nullable: true
status_color:
type: string
nullable: true
status_title:
type: string
nullable: true
steps:
type: array
items:
$ref: '#/components/schemas/step'
tags:
type: string
nullable: true
tags_id:
type: string
nullable: true
team:
type: integer
timestamped:
type: integer
timestampedby:
type: integer
nullable: true
timestamped_at:
type: string
nullable: true
title:
type: string
type:
type: string
up_item_id:
type: integer
nullable: true
uploads:
type: array
items:
$ref: '#/components/schemas/upload'
userid:
type: integer
event:
type: object
properties:
title:
type: string
id:
type: integer
start:
type: string
end:
type: string
userid:
type: integer
item_title:
type: string
color:
type: string
fullname:
type: string
item_link:
type: integer
item_link_title:
type: string
experiment:
type: integer
experiment_title:
type: string
experiment:
allOf:
- $ref: '#/components/schemas/entity'
experiment_template:
type: object
properties:
id:
type: integer
title:
type: string
body:
type: string
nullable: true
category:
type: integer
nullable: true
category_title:
type: string
nullable: true
category_color:
type: string
nullable: true
userid:
type: integer
canread:
type: string
canwrite:
type: string
locked:
type: integer
lockedby:
type: integer
nullable: true
locked_at:
type: string
fullname:
type: string
metadata:
type: string
nullable: true
teams_id:
type: integer
is_pinned:
type: integer
sharelink:
type: string
status:
type: integer
nullable: true
status_title:
type: string
nullable: true
status_color:
type: string
nullable: true
tags:
type: string
nullable: true
tags_id:
type: string
nullable: true
uploads:
type: array
items:
$ref: '#/components/schemas/upload'
idp:
type: object
properties:
id:
type: integer
name:
type: string
entityid:
type: string
sso_url:
type: string
sso_binding:
type: string
slo_url:
type: string
slo_binding:
type: string
x509:
type: string
x509_new:
type: string
enabled:
type: integer
email_attr:
type: string
team_attr:
type: string
fname_attr:
type: string
lname_attr:
type: string
item:
allOf:
- $ref: '#/components/schemas/entity'
- type: object
properties:
is_bookable:
type: integer
canbook:
type: string
book_max_minutes:
type: integer
book_max_slots:
type: integer
book_can_overlap:
type: integer
book_users_can_in_past:
type: integer
book_is_cancellable:
type: integer
book_cancel_minutes:
type: integer
items_type:
type: object
properties:
id:
type: integer
title:
type: string
status:
type: integer
color:
type: string
body:
type: string
ordering:
type: integer
canread:
type: string
canwrite:
type: string
metadata:
type: string
link:
type: object
properties:
entityid:
type: integer
title:
type: string
is_bookable:
type: integer
link_state:
type: integer
category_color:
type: string
category_title:
type: string
status_color:
type: string
status_title:
type: string
custom_id:
type: integer
page:
type: string
type:
type: string
notification:
type: object
properties:
id:
type: integer
category:
type: integer
is_ack:
type: integer
created_at:
type: string
userid:
type: integer
send_email:
type: integer
email_sent_at:
type: string
body:
type: string
revision:
type: object
properties:
id:
type: integer
item_id:
type: integer
body:
type: string
body_html:
type: string
content_type:
type: integer
created_at:
type: string
userid:
type: integer
metadata:
type: string
# experiments_status, experiments_categories and items_status are statuslike
statuslike:
type: object
properties:
id:
type: integer
title:
type: string
color:
type: string
is_default:
type: integer
step:
type: object
properties:
id:
type: integer
item_id:
type: integer
body:
type: string
ordering:
type: integer
finished:
type: integer
finished_time:
type: string
deadline:
type: string
deadline_notif:
type: integer
tag:
type: object
properties:
id:
type: integer
tag:
type: string
team:
type: object
properties:
id:
type: integer
name:
type: string
common_template:
type: string
common_template_md:
type: string
user_create_tag:
type: integer
force_exp_tpl:
type: integer
link_name:
type: string
link_href:
type: string
created_at:
type: string
orgid:
type: string
force_canread:
type: string
force_canwrite:
type: string
do_force_canread:
type: integer
do_force_canwrite:
type: integer
visible:
type: integer
announcement:
description: Text shown on top of every page for all users of this team.
type: string
nullable: true
onboarding_email_active:
description: Do we send onboarding emails to new users?
enum: [0, 1]
type: integer
onboarding_email_body:
type: string
nullable: true
onboarding_email_subject:
type: string
nullable: true
teamgroup:
type: object
properties:
id:
type: integer
name:
type: string
users:
type: array
items:
type: object
properties:
userid:
type: integer
fullname:
type: string
todoitem:
type: object
properties:
id:
type: integer
body:
type: string
creation_time:
type: string
ordering:
type: integer
userid:
type: integer
unfinished_step:
type: object
properties:
id:
type: integer
title:
type: string
steps:
type: array
items:
type: string
unfinished_steps:
type: object
properties:
experiments:
type: array
items:
$ref: '#/components/schemas/unfinished_step'
items:
type: array
items:
$ref: '#/components/schemas/unfinished_step'
upload:
type: object
properties:
id:
type: integer
real_name:
type: string
long_name:
type: string
comment:
type: string
item_id:
type: integer
userid:
type: string
type:
type: string
created_at:
type: string
hash:
type: string
hash_algorithm:
type: string
storage:
type: integer
filesize:
type: integer
state:
type: integer
immutable:
type: integer
fullname:
type: string
users:
type: object
properties:
userid:
type: integer
firstname:
type: string
lastname:
type: string
email:
type: string
validated:
type: integer
valid_until:
type: string
archived:
type: integer
last_login:
type: string
fullname:
type: string
orcid:
type: string
orgid:
type: string
auth_service:
type: integer
is_sysadmin:
type: integer
entrypoint:
type: integer
sig_pubkey:
type: string
description: Public signature key (minisign format)
teams:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
usergroup:
type: integer
is_owner:
type: integer
extra_fields_keys:
type: object
properties:
extra_fields_key:
type: string
frequency:
type: integer
security:
- token:
- token
paths:
/apikeys:
summary: Manage API keys
description: Handle operations on API keys.
post:
tags: ['Api keys']
summary: Create an API key
description: >-
Create an API key. The cleartext key is sent back in the location
header.
operationId: post-apikeys
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: A name for the API key.
default: RTFM
canwrite:
type: integer
description: Set to 1 to allow the key to do write actions.
default: 0
responses:
'201':
description: The key has been created.
headers:
location:
description: A fake URL that contains the API key in cleartext
schema:
type: string
get:
tags: ['Api keys']
summary: Read API keys
description: Get list of API keys for currently logged in user.
operationId: get-apikeys
responses:
'200':
description: List API keys for user
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/apikey'
/apikeys/{id}:
summary: Actions on an api key
delete:
tags: ['Api keys']
summary: Delete an API key.
description: Delete an API key
operationId: delete-apikey
requestBody:
content:
application/json: {}
parameters:
- name: id
in: path
description: ID of the API key
required: true
schema:
type: integer
responses:
'204':
description: The key was deleted
/config:
summary: The general instance configuration settings
get:
tags: ['Config']
summary: Read the config
operationId: get-config
responses:
'200':
description: The config settings
content:
application/json:
schema:
$ref: '#/components/schemas/config'
patch:
tags: ['Config']
summary: Modify the config
operationId: patch-config
requestBody:
description: The config values to change.
content:
application/json:
schema:
$ref: '#/components/schemas/config'
responses:
'200':
description: The config was modified.
content:
application/json:
schema:
$ref: '#/components/schemas/config'
delete:
tags: ['Config']
summary: Reset the config to default values
operationId: delete-config
requestBody:
content:
application/json: {}
responses:
'204':
description: The config was reset.
/experiments:
summary: Actions on experiments
post:
tags: ['Experiments']
summary: Create an experiment
operationId: post-experiment
requestBody:
description: Parameters for creating an experiment
content:
application/json:
schema:
type: object
properties:
category_id:
type: integer
description: >-
The template id to use, or 0 to use the common team
template, or -1 to have an empty body.
default: -1
tags:
type: array
description: >-
An array of tags to assign to the created entry.
items:
type: string
default: []
responses:
'201':
description: The experiment has been created.
headers:
location:
description: An URL to the experiment that was created.
schema:
type: string
get:
tags: ['Experiments']
summary: Read all experiments that are accessible
operationId: read-experiments
# Note: this has to be repeated manually for now
# See https://github.com/OAI/OpenAPI-Specification/issues/445
parameters:
- name: q
in: query
schema:
type: string
description: |
Search for a term in title, body or elabid.
examples:
first:
summary: Search for all experiments with the word "test".
value: test
- name: extended
in: query
schema:
type: string
description: |
Extended search (advanced query).
examples:
first:
summary: Search for all items with a rating of 2.
value: "rating:2"
- name: related
in: query
schema:
type: integer
description: |
Look only for entries linked to this item id.
examples:
first:
summary: Look for entries linked to item with id 42.
value: 42
- name: related_origin
in: query
schema:
type: string
enum: ['experiments', 'items']
description: |
When using the "related" query parameter, select the type of the related ID (experiments or items)
examples:
items:
summary: The related entry is a resource.
value: items
experiments:
summary: The related entry is an experiment.
value: experiments
- name: cat
in: query
schema:
type: integer
description: |
The status id of the experiments.
- name: tags[]
in: query
schema:
type: array
items:
type: string
description: |
An array of tags for filtering results containing all of these tags.
- name: limit
in: query
schema:
type: integer
default: 15
description: |
Limit the number of results.
examples:
first:
summary: Limit number of results to 5.
value: 5
- name: offset
in: query
schema:
type: integer
default: 0
description: |
Skip a number of results. Use with limit to work the pagination.
examples:
first:
summary: Skip 3 first results.
value: 3
- name: owner
in: query
schema:
type: integer
description: |
Filter results by author (user id)
examples:
first:
summary: Only display results from user with id 2
value: 2
- name: scope
in: query
schema:
type: integer
enum: [1, 2, 3]
description: |
Set the scope for the results. 1: self, 2: team, 3: everything. It defaults to the user value stored in preferences.
- name: order
in: query
schema:
type: string
enum: ["cat", "comment", "customid", "date", "id", "lastchange", "rating", "status", "title", "user"]
description: |
Change the ordering of the results.
examples:
first:
summary: Order by category
value: cat
second:
summary: Order by custom ID
value: customid
- name: sort
in: query
schema:
type: string
enum: ["asc", "desc"]
description: |
Change the sorting of results: ascending or descending.
responses:
'200':
description: A list of experiments
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/experiment'
/experiments/{id}:
summary: Actions on an experiment
parameters:
- name: id
in: path
description: ID of the experiment
required: true
schema:
type: integer
get:
tags: ['Experiments']
summary: Read an experiment
operationId: get-experiment
parameters:
- name: format
in: query
schema:
type: string
enum: ['csv', 'eln', 'json', 'qrpdf', 'qrpng', 'pdf', 'pdfa', 'zip', 'zipa']
default: json
description: |
Get the entity in a different format like csv, pdf, eln or zip. "pdfa" means archive pdf (PDF/A), same with "zipa".
examples:
first:
summary: Generate a pdf
value: pdf
second:
summary: Generate a csv
value: csv
- name: changelog
in: query
required: false
schema:
type: integer
enum: [0, 1]
description: |
Toggles if the changelog should be included in PDF exports (pdf, pdfa, zip, zipa). Changelog is by default included if the export provides PDF/A, otherwise not.
examples:
first:
summary: Generate PDF exports that always includes the changelog
value: true
second:
summary: Generate PDF exports that always includes the changelog.
value: 1
third:
summary: Generate PDF exports that do not include the changelog.
value: false
responses:
'200':
description: An experiment
content:
application/json:
schema:
$ref: '#/components/schemas/experiment'
patch:
tags: ['Experiments']
summary: Modify an experiment
operationId: patch-experiment
requestBody:
description: Parameters for patching an item
content:
application/json:
schema:
anyOf:
- type: object
properties:
action:
type: string
enum: ['lock', 'pin', 'updatemetadatafield', 'update', 'bloxberg', 'timestamp']
- $ref: '#/components/schemas/experiment'
responses:
'200':
description: The patched experiment
content:
application/json:
schema:
$ref: '#/components/schemas/experiment'
delete:
tags: ['Experiments']
summary: Delete an experiment.
description: The experiment gets soft-deleted.
requestBody:
content:
application/json: {}
operationId: delete-experiment
responses:
'204':
description: The experiment was deleted
# INFO
/info:
summary: Information about the instance
get:
tags: ['Info']
summary: Get information about the instance.
description: Get information about the instance.
operationId: get-info
responses:
'200':
description: Information about the instance
content:
application/json:
schema:
type: object
properties:
elabftw_version:
type: string
description: Current eLabFTW version
example: 4.8.0
elabftw_version_int:
type: integer
description: Current eLabFTW version as an integer
example: 50102
ts_balance:
type: integer
description: Number of timestamp tokens left
example: 461
all_users_count:
type: integer
description: Total count of all users
example: 389
active_users_count:
type: integer
description: Total count of active users
example: 311
items_count:
type: integer
description: Total count of items
example: 666
teams_count:
type: integer
description: Total count of teams
example: 18
experiments_count:
type: integer
description: Total count of experiments
example: 10189
experiments_timestamped_count:
type: integer
description: Total count of experiments with timestamps
example: 1601
uploads_filesize_sum:
type: integer
description: Sum of stored filesize in MySQL for all uploads of the instance.
example: 25681672
uploads_filesize_sum_formatted:
type: string
description: Sum of stored filesize in MySQL for all uploads of the instance, formatted
example: "24.49 MiB"
# ITEMS
/items:
summary: Actions on items
post:
tags: ['Items']
summary: Create an item
operationId: post-item
requestBody:
description: Parameters for creating an item
content:
application/json:
schema:
type: object
properties:
category_id:
type: integer
description: |
Mandatory parameter, an ID corresponding to an items_types in the team.
tags:
type: array
items:
type: string
default: []
responses:
'201':
description: The item has been created.
headers:
location:
description: An URL to the item that was created.
schema:
type: string
get:
tags: ['Items']
summary: Read all items that are accessible
operationId: read-items
# start duplicate from GET /experiments (except related)
parameters:
- name: q
in: query
schema:
type: string
description: |
Search for a term in title, body or elabid.
examples:
first:
summary: Search for all items with the word "test".
value: test
- name: extended
in: query
schema:
type: string
description: |
Extended search (advanced query).
examples:
first:
summary: Search for all items with a rating of 2.
value: "rating:2"
- name: related
in: query
schema:
type: integer
description: |
Look only for entries linked to this item id.
examples:
first:
summary: Look for entries linked to item with id 42.
value: 42
- name: related_origin
in: query
schema:
type: string
enum: ['experiments', 'items']
description: |
When using the "related" query parameter, select the type of the related ID (experiments or items)
examples:
items:
summary: The related entry is a resource.
value: items
experiments:
summary: The related entry is an experiment.
value: experiments
# This one is not exactly copy paste
- name: cat
in: query
schema:
type: integer
description: |
The category id of the items.
- name: tags[]
in: query
schema:
type: array
items:
type: string
description: |
An array of tags for filtering results containing all of these tags.
- name: limit
in: query
schema:
type: integer
default: 15
description: |
Limit the number of results.
examples:
first:
summary: Limit number of results to 5.
value: 5
- name: offset
in: query
schema:
type: integer
default: 0
description: |
Skip a number of results. Use with limit to work the pagination.
examples:
first:
summary: Skip 3 first results.
value: 3
- name: owner
in: query
schema:
type: integer
description: |
Filter results by author (user id)
examples:
first:
summary: Only display results from user with id 2
value: 2
- name: scope
in: query
schema:
type: integer
enum: [1, 2, 3]
description: |
Set the scope for the results. 1: self, 2: team, 3: everything. It defaults to the user value stored in preferences.
- name: order
in: query
schema:
type: string
enum: ["cat", "comment", "customid", "date", "id", "lastchange", "rating", "status", "title", "user"]
description: |
Change the ordering of the results.
examples:
first:
summary: Order by category
value: cat
second:
summary: Order by custom ID
value: customid
- name: sort
in: query
schema:
type: string
enum: ["asc", "desc"]
description: |
Change the sorting of results: ascending or descending.
# end duplicate from GET /experiments
responses:
'200':
description: A list of items
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/item'
/items/{id}:
summary: Actions on an item
parameters:
- name: id
in: path
description: ID of the item
required: true
schema:
type: integer
get:
tags: ['Items']
summary: Read an item
operationId: get-item
parameters:
- name: format
in: query
schema:
type: string
enum: ['csv', 'eln', 'json', 'qrpdf', 'qrpng', 'pdf', 'pdfa', 'zip', 'zipa']
default: json
description: |
Get the entity in a different format like csv, pdf, eln or zip. "pdfa" means archive pdf (PDF/A), same with "zipa".
examples:
first:
summary: Generate a pdf
value: pdf
second:
summary: Generate a csv
value: csv
- name: changelog
in: query
required: false
schema:
type: integer
enum: [0,1]
description: |
Toggles if the changelog should be included in PDF exports (pdf, pdfa, zip, zipa). Changelog is by default included if the export provides PDF/A, otherwise not.
examples:
first:
summary: Generate PDF exports that always includes the changelog
value: true
second:
summary: Generate PDF exports that always includes the changelog.
value: 1
third:
summary: Generate PDF exports that do not include the changelog.
value: false
responses:
'200':
description: An item
content:
application/json:
schema:
$ref: '#/components/schemas/item'
patch:
tags: ['Items']
summary: Modify an item
operationId: patch-item
requestBody:
description: Parameters for patching an item
content:
application/json:
schema:
anyOf:
- type: object
properties:
action:
type: string
enum: ['lock', 'pin', 'updatemetadatafield', 'update']
- $ref: '#/components/schemas/item'
responses:
'200':
description: The patched item
content:
application/json:
schema:
$ref: '#/components/schemas/item'
delete:
tags: ['Items']
summary: Delete an item.
description: The item gets soft-deleted.
operationId: delete-item
requestBody:
content:
application/json: {}
responses:
'204':
description: The key was deleted
# COMMENTS
/{entity_type}/{id}/comments:
summary: Actions on comments of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
post:
tags: ['Comments']
summary: Create a comment.
operationId: post-entity-comments
requestBody:
description: Parameters for creating a comment
content:
application/json:
schema:
required: ['comment']
type: object
properties:
comment:
type: string
responses:
'201':
description: The comment has been created.
headers:
location:
description: An URL to the comment that was created.
schema:
type: string
get:
tags: ['Comments']
summary: Read all comments of that entity.
operationId: read-entity-comments
responses:
'200':
description: A list of comments
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/comment'
/{entity_type}/{id}/comments/{subid}:
summary: Actions on comment of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the comment
required: true
schema:
type: integer
get:
tags: ['Comments']
summary: Read a comment of that entity.
operationId: read-entity-comment
responses:
'200':
description: A comment.
content:
application/json:
schema:
$ref: '#/components/schemas/comment'
patch:
tags: ['Comments']
summary: Modify an entity comment.
operationId: patch-entity-comment
requestBody:
description: Parameters for patching an entity comment.
content:
application/json:
schema:
$ref: '#/components/schemas/comment'
responses:
'200':
description: The patched comment
content:
application/json:
schema:
$ref: '#/components/schemas/comment'
delete:
tags: ['Comments']
summary: Delete an entity comment.
description: The comment gets deleted.
operationId: delete-entity-comment
requestBody:
content:
application/json: {}
responses:
'204':
description: The comment was deleted
# ITEMS LINKS
/{entity_type}/{id}/items_links:
summary: Links from entity to items.
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
get:
tags: ['Links to items']
summary: Read all items links of that entity.
operationId: read-entity-items-links
responses:
'200':
description: A list of links
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/link'
/{entity_type}/{id}/items_links/{subid}:
summary: Actions on items link of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the item (link)
required: true
schema:
type: integer
post:
tags: ['Links to items']
summary: Create or import a link.
operationId: post-entity-items-links
requestBody:
description: Parameters for creating or importing a link.
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: ['create', 'duplicate']
description: |
The `duplicate` action will import the links of that link (inception).
responses:
'201':
description: The link has been created.
headers:
location:
description: An URL to the link that was created.
schema:
type: string
delete:
tags: ['Links to items']
summary: Delete an item link.
description: The link gets deleted.
operationId: delete-entitiy-items-link
requestBody:
content:
application/json: {}
responses:
'204':
description: The link was deleted.
# EXPERIMENTS LINKS
/{entity_type}/{id}/experiments_links:
summary: Links from entity to experiments.
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
get:
tags: ['Links to experiments']
summary: Read all experiments links of that entity.
operationId: read-entity-experiments-links
responses:
'200':
description: A list of links
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/link'
/{entity_type}/{id}/experiments_links/{subid}:
summary: Actions on experiments link of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the experiment linked
required: true
schema:
type: integer
post:
tags: ['Links to experiments']
summary: Create or import a link.
operationId: post-entity-experiments-links
requestBody:
description: Parameters for creating or importing a link.
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: ['create', 'duplicate']
description: |
The `duplicate` action will import the links of that link (inception).
responses:
'201':
description: The link has been created.
headers:
location:
description: An URL to the link that was created.
schema:
type: string
delete:
tags: ['Links to experiments']
summary: Delete an experiment link.
description: The link gets deleted.
operationId: delete-entity-experiments-link
requestBody:
content:
application/json: {}
responses:
'204':
description: The link was deleted.
# EXPERIMENTS_TEMPLATES
/experiments_templates:
summary: Actions on experiments_templates
post:
tags: ['Experiments templates']
summary: Create an experiment template
operationId: post-experiment_template
requestBody:
description: Parameters for creating an experiment template
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: A title for the template.
default: Untitled
responses:
'201':
description: The experiment template has been created.
headers:
location:
description: An URL to the experiment template that was created.
schema:
type: string
get:
tags: ['Experiments templates']
summary: Read all experiments_templates that are accessible
operationId: read-experiments_templates
responses:
'200':
description: A list of experiments_templates
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/experiment_template'
/experiments_templates/{id}:
summary: Actions on an experiment template
parameters:
- name: id
in: path
description: ID of the experiment template
required: true
schema:
type: integer
get:
tags: ['Experiments templates']
summary: Read an experiment template
operationId: get-experiment_template
responses:
'200':
description: An experiment template
content:
application/json:
schema:
$ref: '#/components/schemas/experiment_template'
patch:
tags: ['Experiments templates']
summary: Modify an experiment template
operationId: patch-experiment_template
requestBody:
description: Parameters for modifying an experiment template
content:
application/json:
schema:
anyOf:
- type: object
properties:
action:
type: string
enum: ['lock', 'pin', 'update']
- $ref: '#/components/schemas/experiment_template'
responses:
'200':
description: The patched experiment template
content:
application/json:
schema:
$ref: '#/components/schemas/experiment_template'
delete:
tags: ['Experiments templates']
summary: Delete an experiment template.
description: The experiment template gets soft-deleted.
operationId: delete-experiment_template
requestBody:
content:
application/json: {}
responses:
'204':
description: The key was deleted
# ITEMS_TYPES
/items_types:
summary: Actions on resources categories, aka items types
post:
tags: ['Items types']
summary: Create a resource category
operationId: post-items_types
requestBody:
description: Parameters for creating a resource category
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: A name for this items type.
default: Untitled
responses:
'201':
description: The items type has been created.
headers:
location:
description: An URL to the items type that was created.
schema:
type: string
get:
tags: ['Items types']
summary: Read all resources categories that are accessible.
operationId: read-items_types
responses:
'200':
description: A list of resources categories.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/items_type'
/items_types/{id}:
summary: Actions on a resource category.
parameters:
- name: id
in: path
description: ID of the resource category.
required: true
schema:
type: integer
get:
tags: ['Items types']
summary: Read a resource category.
operationId: get-items_type
responses:
'200':
description: A resource category.
content:
application/json:
schema:
$ref: '#/components/schemas/items_type'
patch:
tags: ['Items types']
summary: Modify a resource category.
operationId: patch-items_type
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/items_type'
responses:
'200':
description: The patched resource category.
content:
application/json:
schema:
$ref: '#/components/schemas/items_type'
delete:
tags: ['Items types']
summary: Delete a resource category.
description: The resource category gets soft-deleted.
operationId: delete-items_type
requestBody:
content:
application/json: {}
responses:
'204':
description: The resource category was marked as deleted.
# EVENTS
/events:
summary: For scheduler booking.
get:
tags: ['Events']
summary: Read all events in the team.
operationId: read-events
responses:
'200':
description: A list of booked slots.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/event'
/events/{id}:
parameters:
- name: id
in: path
description: ID of the item to book.
required: true
schema:
type: integer
post:
tags: ['Events']
summary: Create an event for the item specified as id.
operationId: post-events
requestBody:
description: Parameters for creating an event.
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: A name for this booking slot.
default: Untitled
start:
type: string
description: A starting date-time in ISO 8601 format.
end:
type: string
description: An end date-time in ISO 8601 format.
responses:
'201':
description: The booking slot has been created.
headers:
location:
description: An URL to the booking slot that was created.
schema:
type: string
# EVENT
/event/{id}:
summary: For scheduler booking.
parameters:
- name: id
in: path
description: ID of the event to modify.
required: true
schema:
type: integer
get:
tags: ['Events']
summary: Read a booking slot.
operationId: read-event
responses:
'200':
description: A particular event
content:
application/json:
schema:
$ref: '#/components/schemas/event'
patch:
tags: ['Events']
summary: |
Modify a booking slot. Warning: only one value (target) can be edited at a time.
operationId: patch-event
requestBody:
description: Parameters for modifying an event.
content:
application/json:
schema:
oneOf:
- type: object
properties:
target:
type: string
enum: ['start_epoch', 'end_epoch']
epoch:
type: string
description: Date-time in UNIX epoch format.
- type: object
properties:
target:
type: string
enum: ['experiment', 'item_link']
id:
type: integer
description: Entity id.
- type: object
properties:
target:
type: string
enum: ['start', 'end']
delta:
type: object
description: The difference (delta) of time with the previous value.
properties:
days:
type: integer
milliseconds:
type: integer
months:
type: integer
years:
type: integer
responses:
'200':
description: The patched event.
content:
application/json:
schema:
$ref: '#/components/schemas/event'
delete:
tags: ['Events']
summary: Delete a booking slot.
operationId: delete-event
requestBody:
content:
application/json: {}
responses:
'204':
description: The event was deleted.
# FAVTAGS
/favtags:
summary: Favorite tags for the logged-in user.
get:
tags: ['Favorite tags']
summary: Read all favorite tags for the user.
operationId: read-favtags
responses:
'200':
description: A list of favorite tags.
content:
application/json:
schema:
type: object
properties:
users_id:
type: integer
tags_id:
type: integer
tag:
type: string
post:
tags: ['Favorite tags']
summary: Add a tag as favorite.
operationId: post-favtags
requestBody:
description: Parameters for adding a favorite tag.
content:
application/json:
schema:
type: object
properties:
tag:
type: string
description: An existing tag
responses:
'201':
description: The favtag has been created.
headers:
location:
description: |
Favorite tags don't have an ID, so the returned URL in Location in invalid.
schema:
type: string
/favtags/{id}:
summary: A particular favorite tag.
parameters:
- name: id
in: path
description: ID of the tag.
required: true
schema:
type: integer
delete:
tags: ['Favorite tags']
summary: Unfavorite a tag.
operationId: delete-favtag
requestBody:
content:
application/json: {}
responses:
'204':
description: The favorite tag was removed.
# TEAM TAGS
/team_tags:
summary: Manage tags at the team level.
get:
tags: ['Team tags']
summary: Read all tags for the team.
operationId: read-team_tags
responses:
'200':
description: A list of tags.
content:
application/json:
schema:
type: object
properties:
tag:
type: string
id:
type: integer
item_count:
type: integer
post:
tags: ['Team tags']
summary: Create a tag in the team.
operationId: post-team_tag
requestBody:
description: Parameters for adding a tag in the team.
content:
application/json:
schema:
type: object
properties:
tag:
type: string
description: Tag to add
responses:
'201':
description: The tag has been added.
headers:
location:
description: An URL ending with 0 if the tag was already here, or an URL to the newly created tag.
schema:
type: string
patch:
tags: ['Team tags']
summary: |
Actions on tags.
operationId: patch-tags
requestBody:
description: Parameters for modifying team tags.
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: ['deduplicate']
description: Find all duplicate tags and deduplicate them.
responses:
'200':
description: The team tag has been modified.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/tag'
/team_tags/{id}:
summary: Retrieve a tag from its id.
parameters:
- name: id
in: path
description: ID of the tag.
required: true
schema:
type: integer
get:
tags: ['Team tags']
summary: Read a tag.
operationId: read-team_tag
responses:
'200':
description: A tag.
content:
application/json:
schema:
type: object
properties:
tag:
type: string
id:
type: integer
patch:
tags: ['Team tags']
summary: |
Actions on a tag.
operationId: patch-team_tag
requestBody:
description: Parameters for modifying a tag.
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: ['updatetag']
tag:
type: string
description: The content of the tag.
description: Update the tag. Requires Admin permissions.
responses:
'200':
description: The team tag has been modified.
content:
application/json:
schema:
$ref: '#/components/schemas/tag'
delete:
tags: ['Team tags']
summary: Delete a tag.
operationId: delete-team_tag
requestBody:
content:
application/json: {}
responses:
'204':
description: The tag was removed.
# TEAMS
/teams:
summary: Manage teams.
get:
tags: ['Teams']
summary: Read all teams. Requires Sysadmin permissions.
operationId: read-teams
responses:
'200':
description: A list of teams.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/team'
post:
tags: ['Teams']
summary: Create a new team.
operationId: post-teams
requestBody:
description: Parameters for creating a new team.
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Team name.
default: New team name
responses:
'201':
description: The team has been created.
headers:
location:
description: An URL to the team that was created.
schema:
type: string
/teams/{id}:
summary: Manage a team.
parameters:
- name: id
in: path
description: ID of the team or `current`.
required: true
schema:
oneOf:
- type: integer
- type: string
enum: ['current']
examples:
first:
summary: Access the current team.
value: 'current'
second:
summary: Access team with ID 3.
value: 3
get:
tags: ['Teams']
summary: Read a team. Requires Admin permissions.
operationId: read-team
responses:
'200':
description: A team.
content:
application/json:
schema:
$ref: '#/components/schemas/team'
patch:
tags: ['Teams']
summary: |
Actions on a team.
operationId: patch-team
requestBody:
description: Parameters for modifying a team.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/team'
- type: object
description: (Re)send the onboarding email to all users specified in the userids property. Only admins can send emails to their team members.
properties:
action:
enum: ['sendonboardingemails']
type: string
userids:
description: A list of user ids for which the onboarding email shall be sent.
type: array
items:
type: integer
example: [5, 11, 7, 31]
responses:
'200':
description: The updated team.
content:
application/json:
schema:
$ref: '#/components/schemas/team'
# EXPERIMENTS CATEGORIES
/teams/{id}/experiments_categories:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
get:
tags: ['Experiments categories']
summary: Read experiments categories of a team.
operationId: read-team-experiments-categories
responses:
'200':
description: A list of experiments categories for the team.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/statuslike'
post:
tags: ['Experiments categories']
operationId: post-team-one-expcat
summary: Create a new category for experiments.
requestBody:
description: Parameters for creating a category.
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Category name
color:
type: string
description: |
Hex color without leading \#.
default:
type: integer
description: Is it the default category for the team?
responses:
'201':
description: Create a category.
headers:
location:
description: An URL to the category that was created.
schema:
type: string
# ONE EXPERIMENTS CATEGORY
/teams/{id}/experiments_categories/{subid}:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the category.
required: true
schema:
type: integer
get:
tags: ['Experiments categories']
operationId: read-team-one-expcat
summary: Read a category.
responses:
'200':
description: Read a category.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
patch:
tags: ['Experiments categories']
operationId: patch-expcat
summary: Modify a category.
requestBody:
description: Parameters for modifying a category.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
responses:
'200':
description: The updated category.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
delete:
tags: ['Experiments categories']
summary: Delete a category.
operationId: delete-expcat
requestBody:
content:
application/json: {}
responses:
'204':
description: The category was removed.
# EXPERIMENTS STATUS
/teams/{id}/experiments_status:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
get:
tags: ['Experiments status']
summary: Read experiments status of a team.
operationId: read-team-experiments-status
responses:
'200':
description: A list of status for the team.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/statuslike'
post:
tags: ['Experiments status']
operationId: post-team-one-expstatus
summary: Create a new experiments status.
requestBody:
description: Parameters for creating a status.
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Status name
color:
type: string
description: |
Hex color without leading \#.
default:
type: integer
description: Is it the default status for the team?
responses:
'201':
description: New experiments status created.
headers:
location:
description: An URL to the experiments status that was created.
schema:
type: string
# ONE EXPERIMENTS STATUS
/teams/{id}/experiments_status/{subid}:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the status
required: true
schema:
type: integer
get:
tags: ['Experiments status']
operationId: read-team-one-expstatus
summary: Read a status.
responses:
'200':
description: Read a status.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
patch:
tags: ['Experiments status']
operationId: patch-expstatus
summary: Modify a status.
requestBody:
description: Parameters for modifying a status.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
responses:
'200':
description: The updated status.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
delete:
tags: ['Experiments status']
summary: Delete a status.
operationId: delete-expstatus
requestBody:
content:
application/json: {}
responses:
'204':
description: The status was removed.
# ITEMS STATUS
/teams/{id}/items_status:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
get:
tags: ['Resources status']
summary: Read resources status of a team.
operationId: read-team-items-status
responses:
'200':
description: A list of resources status for the team.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/statuslike'
post:
tags: ['Resources status']
operationId: post-team-one-resstat
summary: Create a new status for resources.
requestBody:
description: Parameters for creating a resources status.
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Status name
color:
type: string
description: |
Hex color without leading \#.
default:
type: integer
description: Is it the default status for the team?
responses:
'201':
description: New resources status created.
headers:
location:
description: An URL to the resources status that was created.
schema:
type: string
# ONE ITEMS STATUS
/teams/{id}/items_status/{subid}:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the status
required: true
schema:
type: integer
get:
tags: ['Resources status']
operationId: read-team-one-resstatus
summary: Read a status.
responses:
'200':
description: Read a status.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
patch:
tags: ['Resources status']
operationId: patch-resstatus
summary: Modify a status.
requestBody:
description: Parameters for modifying a status.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
responses:
'200':
description: The updated status.
content:
application/json:
schema:
$ref: '#/components/schemas/statuslike'
delete:
tags: ['Resources status']
summary: Delete a status.
operationId: delete-resstatus
requestBody:
content:
application/json: {}
responses:
'204':
description: The status was removed.
# TEAMGROUPS
/teams/{id}/teamgroups:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
get:
tags: ['Teamgroups']
summary: Read teamgroups of a team.
operationId: read-team-teamgroups
responses:
'200':
description: A list of teamgroups for the team.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/teamgroup'
post:
tags: ['Teamgroups']
operationId: post-teamgroups
summary: Create a new teamgroup.
requestBody:
description: Parameters for creating a teamgroup.
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Teamgroup name
responses:
'201':
description: New teamgroup.
headers:
location:
description: An URL to the teamgroup that was created.
schema:
type: string
/teams/{id}/teamgroups/{subid}:
parameters:
- name: id
in: path
description: ID of the team.
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the teamgroup.
required: true
schema:
type: integer
get:
tags: ['Teamgroups']
operationId: read-teamgroup
summary: Read a teamgroup.
responses:
'200':
description: A teamgroup.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string
team:
type: integer
patch:
tags: ['Teamgroups']
operationId: patch-teamgroup
summary: Modify a teamgroup.
requestBody:
description: Parameters for modifying a teamgroup.
content:
application/json:
schema:
oneOf:
- type: object
properties:
how:
type: string
enum: ['unreference', 'add']
userid:
type: integer
- type: object
properties:
name:
type: string
responses:
'200':
description: The updated teamgroup.
content:
application/json:
schema:
$ref: '#/components/schemas/teamgroup'
delete:
tags: ['Teamgroups']
summary: Delete a teamgroup.
operationId: delete-teamgroup
requestBody:
content:
application/json: {}
responses:
'204':
description: The teamgroup was removed.
# TODOLIST
/todolist:
summary: Todolist for current user.
get:
tags: ['Todolist']
summary: Read all todoitems.
operationId: read-todolist
responses:
'200':
description: A list of things to do.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/todoitem'
post:
tags: ['Todolist']
summary: Create a todo item
operationId: post-todolist
requestBody:
description: Parameters for creating a todoitem.
content:
application/json:
schema:
type: object
properties:
content:
type: string
description: What to do
responses:
'201':
description: The todo entry has been created.
headers:
location:
description: An URL to the todo item that was created.
schema:
type: string
/todolist/{id}:
summary: Manage a todo entry.
parameters:
- name: id
in: path
description: ID of the todoitem.
required: true
schema:
type: integer
get:
tags: ['Todolist']
summary: Read a todo entry.
operationId: read-todoitem
responses:
'200':
description: A todoitem.
content:
application/json:
schema:
$ref: '#/components/schemas/todoitem'
patch:
tags: ['Todolist']
summary: |
Actions on a todoitem.
operationId: patch-todoitem
requestBody:
description: Parameters for modifying a todoitem.
content:
application/json:
schema:
required: ['body']
type: object
properties:
body:
type: string
responses:
'200':
description: The updated todoitem.
content:
application/json:
schema:
$ref: '#/components/schemas/todoitem'
delete:
tags: ['Todolist']
summary: Delete a todoitem.
operationId: delete-todoitem
requestBody:
content:
application/json: {}
responses:
'204':
description: The todoitem was removed.
# UNFINISHED STEPS
/unfinished_steps:
summary: Unfinished steps from the user or the team, in experiments or items.
parameters:
- name: scope
in: query
description: |
Set to "team" to extend the list to other members.
schema:
type: string
default: 'user'
enum: ['team', 'user']
get:
tags: ['Unfinished steps']
summary: Read all unfinished steps.
operationId: read-unfinished-steps
responses:
'200':
description: A list of unfinished steps
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/unfinished_steps'
# USERS
/users:
summary: Display information about users on the instance.
get:
tags: ['Users']
summary: Read users from instance.
description: If Sysadmin all users will be shown. If Admin only the users from the team. Normal users will be shown an error.
operationId: read-users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
userid:
type: integer
firstname:
type: string
lastname:
type: string
orgid:
type: string
nullable: true
email:
type: string
validated:
type: integer
archived:
type: integer
last_login:
type: string
nullable: true
valid_until:
type: string
nullable: true
is_sysadmin:
type: integer
fullname:
type: string
orcid:
type: string
nullable: true
auth_service:
type: integer
nullable: true
example:
- userid: 4
firstname: Brook
lastname: Hegmann
orgid: "u3051"
email: brook@example.com
validated: 1
archived: 0
last_login: "2023-07-29 20:34:04"
valid_until: null
is_sysadmin: 0
fullname: Brook Hegmann
orcid: "0000-0002-7494-5555"
auth_service: null
post:
tags: ['Users']
summary: Create a new user.
description: |
An Admin can create a user in its own team only. A sysadmin can specify the team.
operationId: post-user
requestBody:
description: Parameters for creating a user.
content:
application/json:
schema:
required: ['firstname', 'lastname', 'email']
type: object
properties:
firstname:
type: string
description: User's first name.
lastname:
type: string
description: User's last name.
email:
type: string
description: User's email address.
team:
type: integer
description: The team id.
valid_until:
type: string
description: Date in the YYYY-MM-DD format for account expiration date.
orgid:
type: string
description: Internal id.
usergroup:
type: integer
description: Which permissions level the user will get? `1` is Sysadmin, `2` is Admin, `4` is user (default)
enum: [1, 2, 4]
responses:
'201':
description: The user has been created.
headers:
location:
description: An URL to the user that was created.
schema:
type: string
/users/{id}:
summary: Display information about a particular user.
parameters:
- name: id
in: path
description: ID of the user or `me`.
required: true
schema:
oneOf:
- type: integer
- type: string
enum: ['me']
examples:
first:
summary: Access our own user.
value: 'me'
second:
summary: Access user with ID 42.
value: 42
get:
tags: ['Users']
summary: Read information of a user.
description: |
Note: it is possible to use "me" instead of the userid to access the user of the API key.
operationId: read-user
responses:
'200':
description: Public properties of a user.
content:
application/json:
schema:
$ref: '#/components/schemas/users'
patch:
tags: ['Users']
summary: Modify a user.
description: |
Note: it is possible to use "me" instead of the userid to access the user of the API key.
operationId: patch-user
requestBody:
description: Parameters for modifying a user.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/users'
- type: object
description: Archive or validate a user (will toggle the attribute)
properties:
action:
type: string
enum: ['archive', 'validate']
- type: object
description: Add or remove a user from a team.
properties:
action:
enum: ['add', 'unreference']
type: string
team:
type: integer
description: ID of the team
- type: object
description: Disable 2FA (requires Sysadmin privilege or acting on ourself)
properties:
action:
enum: ['disable2fa']
type: string
- type: object
description: Change the password
properties:
action:
enum: ['updatepassword']
type: string
current_password:
type: string
description: |
Current password. Note: Sysadmin user doesn't need to provide it.
password:
type: string
description: New password.
- type: object
description: Modify ownership of a team
properties:
action:
enum: ['patchuser2team']
type: string
team:
type: integer
description: ID of the team
userid:
type: integer
description: Target userid
target:
type: string
enum: ['group', 'is_owner']
description: The attribute to modify
content:
type: integer
description: Binary value for `is_owner`, integer for `group` (2 for Admin, 4 for User)
responses:
'200':
description: Public properties of a user.
content:
application/json:
schema:
$ref: '#/components/schemas/users'
# NOTIFICATIONS
/users/{id}/notifications:
parameters:
- name: id
in: path
description: ID of the user or `me`.
required: true
schema:
oneOf:
- type: integer
- type: string
enum: ['me']
examples:
first:
summary: Access our own user.
value: 'me'
second:
summary: Access user with ID 42.
value: 42
get:
tags: ['Notifications']
summary: Read notifications of a user.
operationId: read-notifications
responses:
'200':
description: Notifications of a user.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
category:
type: integer
body:
type: object
is_ack:
type: integer
created_at:
type: string
userid:
type: integer
delete:
tags: ['Notifications']
summary: Delete all notifications of the user.
description: All notifications for the user are deleted.
operationId: delete-notifications
requestBody:
content:
application/json: {}
responses:
'204':
description: The notifications were deleted.
/users/{id}/notifications/{subid}:
parameters:
- name: id
in: path
description: ID of the user or `me`.
required: true
schema:
oneOf:
- type: integer
- type: string
enum: ['me']
examples:
first:
summary: Access our own user.
value: 'me'
second:
summary: Access user with ID 42.
value: 42
- name: subid
in: path
description: ID of the notification.
required: true
schema:
type: integer
get:
tags: ['Notifications']
summary: Read a notification.
operationId: read-notification
responses:
'200':
description: A notification.
content:
application/json:
schema:
$ref: '#/components/schemas/notification'
patch:
tags: ['Notifications']
summary: |
Actions on a notification. Only changing `is_ack` column is possible.
operationId: patch-notification
responses:
'200':
description: The updated notification.
content:
application/json:
schema:
$ref: '#/components/schemas/notification'
# STEPS
/{entity_type}/{id}/steps:
summary: Show steps for this entity.
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items', 'experiments_templates', 'items_types']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
get:
tags: ['Steps']
summary: Read all steps of that entity.
operationId: read-steps
responses:
'200':
description: A list of steps
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/step'
post:
tags: ['Steps']
summary: Create a step.
operationId: post-step
requestBody:
description: Parameters for creating a step.
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: |
The text content of the step.
responses:
'201':
description: The step has been created.
headers:
location:
description: An URL to the step that was created.
schema:
type: string
/{entity_type}/{id}/steps/{subid}:
summary: Actions on step of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items', 'experiments_templates', 'items_types']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the step
required: true
schema:
type: integer
patch:
tags: ['Steps']
summary: |
Actions on a step.
operationId: patch-step
requestBody:
description: Parameters for modifying a step
content:
application/json:
schema:
type: object
required: ['action']
properties:
action:
type: string
enum: ['finish', 'notif', 'update']
responses:
'200':
description: The updated step.
content:
application/json:
schema:
$ref: '#/components/schemas/step'
delete:
tags: ['Steps']
summary: Delete a step.
description: The step gets deleted.
operationId: delete-step
requestBody:
content:
application/json: {}
responses:
'204':
description: The step was deleted.
# TAGS
/{entity_type}/{id}/tags:
summary: Show tags for this entity.
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items', 'experiments_templates', 'items_types']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
get:
tags: ['Tags']
summary: Read all tags of that entity.
operationId: read-tags
responses:
'200':
description: A list of tags
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/tag'
post:
tags: ['Tags']
summary: Create a tag.
operationId: post-tag
requestBody:
description: Parameters for creating a tag.
content:
application/json:
schema:
type: object
properties:
tag:
type: string
description: |
The text content of the tag.
responses:
'201':
description: The tag has been created.
headers:
location:
description: An URL to the tag that was created.
schema:
type: string
delete:
tags: ['Tags']
summary: Delete all tags.
description: All the tags from that entity get removed.
operationId: delete-tag
requestBody:
content:
application/json: {}
responses:
'204':
description: The tags were deleted.
/{entity_type}/{id}/tags/{subid}:
summary: Actions on tag of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items', 'experiments_templates', 'items_types']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the tag
required: true
schema:
type: integer
get:
tags: ['Tags']
summary: Read a tag.
operationId: read-tag
responses:
'200':
description: A tag.
content:
application/json:
schema:
$ref: '#/components/schemas/tag'
patch:
tags: ['Tags']
summary: |
Actions on a tag (like removing it from the entity).
operationId: patch-tag
requestBody:
description: Parameters for modifying a tag
content:
application/json:
schema:
type: object
required: ['action']
properties:
action:
type: string
enum: ['unreference']
responses:
'200':
description: The updated tag.
content:
application/json:
schema:
$ref: '#/components/schemas/tag'
# UPLOADS
/{entity_type}/{id}/uploads:
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
get:
tags: ['Uploads']
summary: Read attached files of that entity.
operationId: read-uploads
responses:
'200':
description: A list of uploads.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/upload'
post:
tags: ['Uploads']
summary: Create an upload.
operationId: post-upload
requestBody:
description: Parameters for creating an upload.
content:
multipart/form-data:
schema:
type: object
required: ['file']
properties:
file:
type: string
format: binary
description: The file to upload.
comment:
type: string
description: Optional file comment.
responses:
'201':
description: The file has been uploaded.
headers:
location:
description: An URL to the uploaded file that was created.
schema:
type: string
/{entity_type}/{id}/uploads/{subid}:
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the upload
required: true
schema:
type: integer
get:
tags: ['Uploads']
summary: Read an upload.
operationId: read-upload
parameters:
- name: format
in: query
schema:
type: string
enum: ['binary', 'json']
default: json
description: |
To download the file itself, use `binary` format parameter. In python library, when downloading a file content, make sure to add ` _preload_content=False` into the call to `read_upload()`.
examples:
first:
summary: Get the attached file
value: binary
responses:
'200':
description: |
An upload. Note: with binary output, Content-Type header will vary depending of the file type being sent.
content:
application/json:
schema:
$ref: '#/components/schemas/upload'
'*/*':
schema:
type: string
format: binary
post:
tags: ['Uploads']
summary: Replace an existing uploaded file. The existing file will be archived and the new one will be added.
operationId: post-upload-replace
requestBody:
description: Parameters for replacing an upload.
content:
multipart/form-data:
schema:
type: object
required: ['file']
properties:
file:
type: string
format: binary
description: The file to upload.
comment:
type: string
description: Optional file comment.
responses:
'201':
description: The file has been uploaded.
headers:
location:
description: An URL to the uploaded file that was created.
schema:
type: string
patch:
tags: ['Uploads']
summary: |
Modify attributes such as "real_name", "comment" or "state" of an upload.
operationId: patch-upload
requestBody:
description: Parameters for modifying an upload attributes.
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: ['update']
real_name:
type: string
comment:
type: string
state:
type: integer
enum: [1, 2, 3]
anyOf:
- required:
- real_name
- required:
- comment
- required:
- state
responses:
'200':
description: The updated upload.
content:
application/json:
schema:
$ref: '#/components/schemas/upload'
delete:
tags: ['Uploads']
summary: Delete an upload.
description: The upload gets deleted.
operationId: delete-upload
requestBody:
content:
application/json: {}
responses:
'204':
description: The upload was deleted.
# IDPS
/idps:
get:
tags: ['Idps']
summary: Read all IDPs.
operationId: read-idps
responses:
'200':
description: A list of idps.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/idp'
post:
tags: ['Idps']
summary: Create an idp.
operationId: post-idp
requestBody:
description: Parameters for creating an idp.
content:
application/json:
schema:
type: object
required: ['name', 'entityid', 'sso_url', 'sso_binding', 'slo_url', 'slo_binding', 'x509', 'x509_new', 'email_attr']
properties:
name:
type: string
description: A name for the IDP.
entityid:
type: string
description: Entityid.
sso_url:
type: string
description: URL for Single Sign-On.
sso_binding:
type: string
description: Binding for SSO.
slo_url:
type: string
description: URL for Single Log-Out.
slo_binding:
type: string
description: Binding for SLO.
x509:
type: string
description: Certificate in PEM format.
x509_new:
type: string
description: Certificate in PEM format for renewal period.
email_attr:
type: string
description: What attribute to look for the email.
team_attr:
type: string
description: What attribute to look for the team.
fname_attr:
type: string
description: What attribute to look for the firstname.
lname_attr:
type: string
description: What attribute to look for the lastname.
orgid_attr:
type: string
description: What attribute to look for the internal id.
responses:
'201':
description: The idp has been created.
headers:
location:
description: An URL to the idp that was created.
schema:
type: string
/idps/{id}:
parameters:
- name: id
in: path
description: ID of the idp
required: true
schema:
type: integer
get:
tags: ['Idps']
summary: Read an idp.
operationId: read-idp
responses:
'200':
description: An idp.
content:
application/json:
schema:
$ref: '#/components/schemas/idp'
patch:
tags: ['Idps']
summary: Actions on an idp.
operationId: patch-idp
requestBody:
description: Parameters for modifying an idp.
content:
application/json:
schema:
type: object
required: ['action']
properties:
action:
type: string
enum: ['update']
responses:
'200':
description: The updated idp.
content:
application/json:
schema:
$ref: '#/components/schemas/idp'
delete:
tags: ['Idps']
summary: Delete an idp.
description: The idp gets deleted.
operationId: delete-idp
requestBody:
content:
application/json: {}
responses:
'204':
description: The idp was deleted.
# REVISIONS
/{entity_type}/{id}/revisions:
summary: Actions on revisions of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items', 'experiments_templates']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
post:
tags: ['Revisions']
summary: Create a revision.
operationId: post-entity-revisions
requestBody:
description: Parameters for creating a revision
content:
application/json:
schema:
required: ['body']
type: object
properties:
body:
type: string
responses:
'201':
description: The revision has been created.
headers:
location:
description: An URL to the revision that was created.
schema:
type: string
get:
tags: ['Revisions']
summary: Read all revisions of that entity.
operationId: read-entity-revisions
responses:
'200':
description: A list of revisions for that entity
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
content_type:
type: integer
created_at:
type: string
fullname:
type: string
/{entity_type}/{id}/revisions/{subid}:
summary: Actions on a revision of an entity
parameters:
- name: entity_type
in: path
description: Entity type
required: true
schema:
type: string
enum: ['experiments', 'items', 'experiments_templates']
- name: id
in: path
description: ID of the entity
required: true
schema:
type: integer
- name: subid
in: path
description: ID of the revision
required: true
schema:
type: integer
get:
tags: ['Revisions']
summary: Read a revision of that entity.
operationId: read-entity-revision
responses:
'200':
description: A revision.
content:
application/json:
schema:
$ref: '#/components/schemas/revision'
patch:
tags: ['Revisions']
summary: Restore a revision.
operationId: patch-entity-revision
requestBody:
description: Parameters for restoring an entity revision.
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: ['replace']
description: |
The `replace` action will restore the revision body to the entity.
responses:
'200':
description: The (unchanged) revision
content:
application/json:
schema:
$ref: '#/components/schemas/revision'
# EXTRA FIELDS KEYS
/extra_fields_keys:
summary: Search for extra fields keys used by a team. Results are sorted by frequency.
parameters:
- name: q
in: query
description: |
Search for a term in the extra fields keys.
schema:
type: string
default: ''
- name: limit
in: query
description: |
Number of extra fields keys that will be returned. Value >= -1; -1: no limit, 0: users default setting from UCP.
schema:
type: integer
default: 0
get:
tags: ['Extra Fields Keys']
summary: Read extra fields keys.
operationId: extra-fields-keys
responses:
'200':
description: A list of extra fields keys and their frequency.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/extra_fields_keys'