@datafire/osf

v5.0.0

Published

3 years ago

DataFire integration for OSF APIv2 Documentation

Downloads

0High
0Medium
0Low

datafire

@datafire/osf

Client library for OSF APIv2 Documentation

Installation and Usage

npm install --save @datafire/osf

let osf = require('@datafire/osf').create();

.then(data => {
  console.log(data);
});

Description

https://api.osf.io/v2/

Actions

base_read

Welcome to the Open Science Framework API. With this API you can access users, projects, components, logs, and files from the Open Science Framework. The Open Science Framework (OSF) is a free, open-source service maintained by the Center for Open Science.

Returns

A JSON object with meta and links keys.

The meta key contains information such as a welcome message from the API, the specified version of the request, and the full representation of the current user, if authentication credentials were provided in the request.

The links key contains links to the following entity collections: addons, collections, institutions, licenses, metaschemas, nodes, registrations, users

osf.base_read(null, context)

Input

This action has no parameters

Output

Output schema unknown

logs_actions

A log can have one of many actions. The complete list of loggable actions (in the format {identifier}: {description}) is as follows:

project_created: A Node is created
project_registered: A Node is registered
project_deleted: A Node is deleted

created_from: A Node is created using an existing Node as a template
pointer_created: A Pointer is created
pointer_forked: A Pointer is forked
pointer_removed: A Pointer is removed
node_removed: A component is deleted
node_forked: A Node is forked

made_public: A Node is made public
made_private: A Node is made private
tag_added: A tag is added to a Node
tag_removed: A tag is removed from a Node
edit_title: A Node's title is changed
edit_description: A Node's description is changed
updated_fields: One or more of a Node's fields are changed
external_ids_added: An external identifier is added to a Node (e.g. the DOI)

view_only_link_added: A view-only link was added to a Node
view_only_link_removed: A view-only link was removed from a Node

contributor_added: A Contributor is added to a Node
contributor_removed: A Contributor is removed from a Node
contributors_reordered: A Contributor's position in a Node's bibliography is changed
permissions_updated: A Contributor`s permissions on a Node are changed
made_contributor_visible: A Contributor is made bibliographically visible on a Node
made_contributor_invisible: A Contributor is made bibliographically invisible on a Node

wiki_updated: A Node's wiki is updated
wiki_deleted: A Node's wiki is deleted
wiki_renamed: A Node's wiki is renamed
made_wiki_public: A Node's wiki is made public
made_wiki_private: A Node's wiki is made private

addon_added: An add-on is linked to a Node
addon_removed: An add-on is unlinked from a Node
addon_file_moved: A File in a Node's linked add-on is moved
addon_file_copied: A File in a Node's linked add-on is copied
addon_file_renamed: A File in a Node's linked add-on is renamed

node_authorized: An addon is authorized for a project
node_deauthorized: An addon is deauthorized for a project

folder_created: A Folder is created in a Node's linked add-on
file_added: A File is added to a Node's linked add-on
file_updated: A File is updated on a Node's linked add-on
file_removed: A File is removed from a Node's linked add-on
file_restored: A File is restored in a Node's linked add-on

comment_added: A Comment is added to some item
comment_removed: A Comment is removed from some item
comment_updated: A Comment is updated on some item

embargo_initiated: An embargoed Registration is proposed on a Node
embargo_approved: A proposed Embargo of a Node is approved
embargo_cancelled: A proposed Embargo of a Node is cancelled
embargo_completed: A proposed Embargo of a Node is completed

retraction_initiated: A Withdrawal of a Registration is proposed
retraction_approved: A Withdrawal of a Registration is approved
retraction_cancelled: A Withdrawal of a Registration is cancelled

registration_initiated: A Registration of a Node is proposed
registration_approved: A proposed Registration is approved
registration_cancelled: A proposed Registration is cancelled

preprint_initiated: A preprint is made from the node (deprecated log, preprints are no longer made from nodes)
preprint_license_updated: A license is added or updated to the preprint (deprecated log, preprint actions are no longer logged on the node)
preprint_file_updated: The primary file of a preprint is updated (deprecated log, this action is now logged on the preprint)

osf.logs_actions(null, context)

Input

This action has no parameters

Output

Output schema unknown

addons_list

A paginated list of addons configurable with the OSF

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of up to 10 addons. Each resource in the array is a separate addon object.

The links key contains a dictionary of links that can be used for pagination.

This request should never return an error.

osf.addons_list(null, context)

Input

This action has no parameters

Output

output array
- items object
  - attributes object: The properties of the addon entity.
    - categories array: List of categories this addon belongs to.
      - items string (values: documentation, storage, bibliography, other, security, citations)
    - description string: The description of the service provider.
    - name string: The name of the third-party service provider.
    - url string: The URL to the third-party service provider.
  - id string: The identifier of the addon entity.
  - type string: The type identifier of the addon entity (addons).

citations_styles_list

A paginated list of all standard citation styles available for rendering citations.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 citation styles. Each resource in the array is a separate citation syle and contains the full representation of the citation style object.

The links key contains a dictionary of links that can be used for pagination.

This request should never return an error.

Filtering

You can optionally request that the response only include citation styles that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/citations/styles/?filter[title]=open.

Citation styles may be filtered by their id, title, short-title, and summary.

You can learn more about advanced filtering features here.

osf.citations_styles_list(null, context)

Input

This action has no parameters

Output

output array
- items object
  - attributes required object: The properties of the citation style entity.
    - date_parsed required string: The time at which the citation style was first parsed, as an iso8601 formatted timestamp.
    - short_title string: The short name for the citation style.
    - summary string: The summary of the citation style.
    - title required string: The official name of the citation style.
  - id required string: The identifier of the citation style, e.g. APA.
  - links object: URLs to alternative representations of the citation style entity.
  - type required string: The type identifier of the citation style entity (citation-styles).

citations_styles_read

Retrieves the details of a citation style.

Returns

Returns a JSON object with a data key containing the representation of the requested citation style, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.citations_styles_read({
  "style_id": ""
}, context)

Input

input object
- style_id required string: The unique identifier of the citation style.

Output

output object
- attributes required object: The properties of the citation style entity.
  - date_parsed required string: The time at which the citation style was first parsed, as an iso8601 formatted timestamp.
  - short_title string: The short name for the citation style.
  - summary string: The summary of the citation style.
  - title required string: The official name of the citation style.
- id required string: The identifier of the citation style, e.g. APA.
- links object: URLs to alternative representations of the citation style entity.
- type required string: The type identifier of the citation style entity (citation-styles).

comments_delete

Deletes a comment. This action can be undone by setting deleted to False in a comment update request.

Returns

If the request is successful, no content is returned.

If the request is unsuccessful, a JSON object with an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.comments_delete({
  "comment_id": ""
}, context)

Input

input object
- comment_id required string: The unique identifier of the comment you wish to delete.

Output

Output schema unknown

comments_read

Retrieves the details of a comment

Returns

Returns a JSON object with a data key containing the representation of the requested comment, if the request was successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.comments_read({
  "comment_id": ""
}, context)

Input

input object
- comment_id required string: The unique identifier of the comment you wish to retrieve.

Output

output object
- attributes object: The properties of the comment entity.
  - can_edit boolean: Whether or not the current user has permission to edit this comment
  - content string: The content of the comment.
  - date_created string: The time at which the comment was created, as an iso8601 formatted timestamp.
  - date_modified string: The time at which the comment was last modified, as an iso8601 formatted timestamp.
  - deleted boolean: Whether or not the comment is deleted.
  - has_children boolean: Whether or not the comment has replies.
  - has_report boolean: Whether or not the comment the current user reported this as spam.
  - is_abuse boolean: Whether or not the comment is flagged or confirmed spam.
  - is_ham boolean: Whether or not an admin checked the legitimacy of this comment.
  - modified boolean: Whether or not the comment has been edited.
  - page string: The page type the comment is on, e.g. node, registration, wiki, files.
- id required string: The identifier of the comment entity.
- links object: URLs to alternative representations of the comment entity.
  - self string: A link to the detail page for the comment.
- relationships object: URLs to other entities or entity collections that have a relationship to the comment entity.
  - node string: A relationship to the node the comment is on.
  - replies string: A relationship to the replies to the comment.
  - reports string: A relationship to the reports connected to the comment.
  - target string: A relationship to the target of the comment.
  - user string: A relationship to the user who created the comment.
- type string: The type identifier of the comment entity (comments).

comments_put

Updates the specified comment by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns

Returns JSON with a data key containing the new representation of the updated comment, if the request is successful.

If the request is unsuccessful, JSON with an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.comments_put({
  "comment_id": "",
  "body": {}
}, context)

Input

input object
- comment_id required string: The unique identifier of the comment you wish to update.
- body required object

Output

Output schema unknown

files_detail

Retrieves the details of a file (or folder)

Returns

Returns a JSON object with a data key containing the metadata for the requested file or folder. If a metadata request is issued against a folder, the request will return the metadata for every object in the folder. If the ?info= query parameter is present for a request against a folder, the response will contain the metadata for the folder itself instead of the metadata for the objects in the folder.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

Waterbutler API actions

Files can be modified via the Waterbutler URLs found in the links key of the response (new_folder, move, upload, download, and delete). Further information about how to interact with files can be found in the Waterbutler API documentation.

Download (files)

To download a file, issue a GET request against the download link. The response will have the Content-Disposition header set, which will will trigger a download in a browser.

Create Subfolder (folders)

You can create a subfolder of an existing folder by issuing a PUT request against the new_folder link. The ?kind=folder portion of the query parameter is already included in the new_folder link. The name of the new subfolder should be provided in the name query parameter. The response will contain a WaterButler folder entity. If a folder with that name already exists in the parent directory, the server will return a 409 Conflict error response.

Upload New File (folders)

To upload a file to a folder, issue a PUT request to the folder's upload link with the raw file data in the request body, and the kind and name query parameters set to 'file' and the desired name of the file. The response will contain a WaterButler file entity that describes the new file. If a file with the same name already exists in the folder, the server will return a 409 Conflict error response.

Update Existing File (file)

To update an existing file, issue a PUT request to the file's upload link with the raw file data in the request body and the kind query parameter set to "file". The update action will create a new version of the file. The response will contain a WaterButler file entity that describes the updated file.

Rename (files, folders)

To rename a file or folder, issue a POST request to the move link with the action body parameter set to "rename" and the rename body parameter set to the desired name. The response will contain either a folder entity or file entity with the new name.

Move & Copy (files, folders)

Move and copy actions both use the same request structure, a POST to the move url, but with different values for the action body parameters. The path parameter is also required and should be the OSF path attribute of the folder being written to. The rename and conflict parameters are optional. If you wish to change the name of the file or folder at its destination, set the rename parameter to the new name. The conflict param governs how name clashes are resolved. Possible values are replace and keep. replace is the default and will overwrite the file that already exists in the target folder. keep will attempt to keep both by adding a suffix to the new file's name until it no longer conflicts. The suffix will be ' (x)' where x is a increasing integer starting from 1. This behavior is intended to mimic that of the OS X Finder. The response will contain either a folder entity or file entity with the new name. Files and folders can also be moved between nodes and providers. The resource parameter is the id of the node under which the file/folder should be moved. It must agree with the path parameter, that is the path must identify a valid folder under the node identified by resource. Likewise, the provider parameter may be used to move the file/folder to another storage provider, but both the resource and path parameters must belong to a node and folder already extant on that provider. Both resource and provider default to the current node and providers. If a moved/copied file is overwriting an existing file, a 200 OK response will be returned. Otherwise, a 201 Created will be returned.

osf.files_detail({
  "file_id": ""
}, context)

Input

input object
- file_id required string: The unique identifier of the file you wish to retrieve.

Output

output array
- items object
  - attributes object: The properties of the file entity.
    - checkout string: SOON TO BE DEPRECATED, see relationships checkout.
    - current_user_can_comment boolean: Whether or not the current user is allowed to post comments.
    - current_version integer: Version number of the file.
    - date_created string: The time at which the file was created, as an iso8601 formatted timestamp.
    - date_modified string: The time at which the file was last modified, as an iso8601 formatted timestamp.
    - delete_allowed boolean: Whether or not deletion of the file is allowed.
    - extra object: Extra information, contains hashes (sha256, md5) and downloads count.
    - guid string: Global unique identifier (GUID) for this file (if one has been assigned).
    - kind string: The kind of files object it is (file or folder).
    - last_touched string: The time at which the file external metadata was last retrieved as an iso8601 formatted timestamp (does not apply to OSF Storage files).
    - materialized_path string: Unix-style path to the file relative to the provider root.
    - name string: Name of the file
    - path string: The unique identifier for this file entity for this project and storage provider.
    - provider string: The id of the file provider (e.g., osfstorage)
    - size integer: Size of the file in bytes.
    - tags array: A list of strings that describe this file, as entered by project contributors.
      - items string
  - id string: The identifier of the file entity.
  - links object: Links to alternative representations of the file entity.
    - delete string: The Waterbutler API route for file deletions.
    - download string: The Waterbutler API route for file downloads.
    - html string: A link to the file on the OSF.
    - info string: A link to the page to view a file's information or a folder's contents.
    - move string: The Waterbutler API route for file moves.
    - new_folder string: The Waterbutler API route for creating a new subfolder (does not exist for files).
    - render string: A Waterbutler API route for rendering the file.
    - self string: A link to the detail page for the file.
    - upload string: The Waterbutler API route for file uploads.
  - relationships object: Links to other entities or entity collections that have a relationship to the file entity.
    - checkout string: A link to the user who checked out the file.
    - comments string: A link to the comments on the file.
    - node string: A link to the node the file is on.
    - versions string: A link to the versions of the file.
  - type string: The type identifier of the file entity (files).

files_patch

Updates the specified file by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns

Returns JSON with a data key containing the new representation of the updated file, if the request is successful.

If the request is unsuccessful, JSON with an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.files_patch({
  "file_id": "",
  "body": {}
}, context)

Input

input object
- file_id required string: The unique identifier of the file you wish to update.
- body required object

Output

Output schema unknown

files_versions

A paginated list of all file versions.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 file versions. Each resource in the array is a separate file version object.

The links key contains a dictionary of links that can be used for pagination.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.files_versions({
  "file_id": ""
}, context)

Input

input object
- file_id required string: The unique identifier of the file from which you want to retrieve versions.

Output

output array
- items object
  - attributes object: The properties of the file versions entity.
    - content_type object: MIME content-type for the file (null if unavailable).
    - date_created string: The date of the file version creation, as an iso8601 formatted timestamp.
    - size integer: Size of the file in bytes.
  - id string: The identifier of the file version.
  - links object: Links to alternative representations of the file version entity.
    - download string: The Waterbutler API route for downloading the version.
    - html string: A link to the html version page.
    - render string: A Waterbutler API route for rendering the version.
    - self string: A link to the detail page for a file version.
  - type string: The type identifier of the file versions entity (file_versions).

files_version_detail

Retrieves the details of a file version

Returns

Returns a JSON object with a data key containing the representation of the requested file, if the request was successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.files_version_detail({
  "file_id": "",
  "version_id": ""
}, context)

Input

input object
- file_id required string: The unique identifier of the file from which you want to retrieve versions.
- version_id required string: The file version number you want to retrieve.

Output

output array
- items object
  - attributes object: The properties of the file versions entity.
    - content_type object: MIME content-type for the file (null if unavailable).
    - date_created string: The date of the file version creation, as an iso8601 formatted timestamp.
    - size integer: Size of the file in bytes.
  - id string: The identifier of the file version.
  - links object: Links to alternative representations of the file version entity.
    - download string: The Waterbutler API route for downloading the version.
    - html string: A link to the html version page.
    - render string: A Waterbutler API route for rendering the version.
    - self string: A link to the detail page for a file version.
  - type string: The type identifier of the file versions entity (file_versions).

groups_list

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

A paginated list of groups. Only groups the logged-in user belongs to will be returned. The returned groups are sorted by their date_modified, with the most recently updated groups appearing first.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 groups. Each resource in the array is a separate group object and contains the full representation of the group, meaning additional requests to a group's detail view are not necessary.

The links key contains a dictionary of links that can be used for pagination.

Filtering

You can optionally request that the response only include groups that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/groups/5c0571f4b146c900085f39a3/?filter[name]=lab.

Groups may be filtered by their name. You can learn more about advanced filtering features here.

osf.groups_list(null, context)

Input

This action has no parameters

Output

output array
- items object
  - attributes required object: The properties of the group entity.
    - date_created string: The time at which the group was created, as an iso8601 formatted timestamp.
    - date_modified string: The time at which the group was last modified, as an iso8601 formatted timestamp.
    - name required string: The name of the group.
  - id string: The unique identifier of the group entity.
  - links object: URLs to alternative representations of the group entity.
    - html string: A link to the group's page on the OSF.
    - self string: A link to the canonical API endpoint of this group.
  - relationships object: URLs to other entities or entity collections that have a relationship to the group entity.
    - members string: A link to the list of the members of this group.
  - type required string: The type identifier of the group entity (groups).

groups

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Creates a new group. On the OSF, a group is a collection of users; examples are a lab group or a class. Users can add other users to groups, and then allow that group to access a project or several projects.

Required

Required fields for creating a group include:

name

Note: The creator is automatically made a manager of the group.

Returns

Returns a JSON object with a data key containing the representation of the created group, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.groups({
  "body": {
    "type": "",
    "attributes": {
      "name": ""
    }
  }
}, context)

Input

input object
- body required object
  - attributes required object: The properties of the group entity.
    - date_created string: The time at which the group was created, as an iso8601 formatted timestamp.
    - date_modified string: The time at which the group was last modified, as an iso8601 formatted timestamp.
    - name required string: The name of the group.
  - id string: The unique identifier of the group entity.
  - links object: URLs to alternative representations of the group entity.
    - html string: A link to the group's page on the OSF.
    - self string: A link to the canonical API endpoint of this group.
  - relationships object: URLs to other entities or entity collections that have a relationship to the group entity.
    - members string: A link to the list of the members of this group.
  - type required string: The type identifier of the group entity (groups).

Output

Output schema unknown

groups_delete

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Permanently deletes a group. This action cannot be undone.

Permissions

Only group managers may delete a group. Attempting to delete a group for which you are not a manager will result in a 403 Forbidden response.

Returns

If the request is successful, no content is returned.

osf.groups_delete({
  "group_id": ""
}, context)

Input

input object
- group_id required string: The unique identifier of the group.

Output

Output schema unknown

groups_read

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Retrieves the details of a given group

Permissions

Any user can retrieve a group. Authentication is not required to view the details of a specific group.

Returns

Returns a JSON object with a data key that has a representation of the serialized group.

osf.groups_read({
  "group_id": ""
}, context)

Input

input object
- group_id required string: The unique identifier of the group.

Output

output object
- attributes required object: The properties of the group entity.
  - date_created string: The time at which the group was created, as an iso8601 formatted timestamp.
  - date_modified string: The time at which the group was last modified, as an iso8601 formatted timestamp.
  - name required string: The name of the group.
- id string: The unique identifier of the group entity.
- links object: URLs to alternative representations of the group entity.
  - html string: A link to the group's page on the OSF.
  - self string: A link to the canonical API endpoint of this group.
- relationships object: URLs to other entities or entity collections that have a relationship to the group entity.
  - members string: A link to the list of the members of this group.
- type required string: The type identifier of the group entity (groups).

group_partial_update

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Updates a group by setting the values of the attributes specified in the request body. Any unspecified attributes will be left unchanged.

Groups can be updated with either a PUT or PATCH request. The name field is mandatory in a PUT request, and optional in a PATCH.

Permissions

Only managers of a group may update the group. Attempting to update a group for which you do not have manager access will result in a 403 Forbidden response.

Returns

Returns a JSON object with a data key containing the new representation of the updated node, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.group_partial_update({
  "group_id": "",
  "body": {}
}, context)

Input

input object
- group_id required string: The unique identifier of the group.
- body required object

Output

Output schema unknown

group_members_list

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

A paginated list of the group members. Groups are collections of users. A user can either be a group member or a group manager. Group managers can update group membership. All group members can be added as a unit to a project or several projects.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 members. Each resource in the array contains the full representation of the member, meaning additional requests to a member's detail view are not necessary. The user's role in the group and full_name are top-level attributes. Additionally, if a member hasn't yet claimed their OSF account, they will have an unregistered_member attribute. To see more details about the user in the group, follow the users relationship. The links key contains a dictionary of links that can be used for pagination.

Filtering

You can optionally request that the response only include members that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/groups/5c0571f4b146c900085f39a3/members/?filter[role]=manager.

Contributors may be filtered by their role and full_name attributes.

You can learn more about advanced filtering features here.

osf.group_members_list({
  "group_id": ""
}, context)

Input

input object
- group_id required string: The unique identifier of the group.

Output

output array
- items object
  - attributes object: The properties of the contributor entity.
    - email string: The unregistered user email. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
    - full_name string: The full name of the user, used for display on the OSF. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
    - role string (values: manager, member): The permission level of the group member. The default value is 'member'.
    - unregistered_member string: The assigned name of the group member if the member has not yet claimed their account.
  - id string: The identifier of the group member entity. Member identifiers have the form {group_id}-{user_id}.
  - links object: URLs to alternative representations of the group member entity.
    - self string: A link to the the canonical API endpoint for the group member.
  - relationships required object: URLs to other entities or entity collections that have a relationship to the group member entity.
    - user required string: A relationship to the user object
  - type required string: The type identifier of the group member entity (group-members).

group_members_create

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Adds a member to a group, effectively creating a relationship between the group and a user. Groups are collections of users. A user can either be a group member or a group manager. Group managers can update group membership. All group members can be added as a unit to a project or several projects.

Permissions

Only a group manager can add a member to the group.

Required

A relationship object with a data key, containing the users type and valid user ID is required. You can specify the member's role with the role attribute. Default role is member. To add an unregistered member to a group, specify a full_name and email combination under attributes.

Returns

Returns a JSON object with a data key containing the representation of the new group member, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.group_members_create({
  "group_id": "",
  "body": {
    "type": "",
    "relationships": {
      "user": ""
    }
  }
}, context)

Input

input object
- group_id required string: The unique identifier of the group.
- body required object
  - attributes object: The properties of the contributor entity.
    - email string: The unregistered user email. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
    - full_name string: The full name of the user, used for display on the OSF. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
    - role string (values: manager, member): The permission level of the group member. The default value is 'member'.
    - unregistered_member string: The assigned name of the group member if the member has not yet claimed their account.
  - id string: The identifier of the group member entity. Member identifiers have the form {group_id}-{user_id}.
  - links object: URLs to alternative representations of the group member entity.
    - self string: A link to the the canonical API endpoint for the group member.
  - relationships required object: URLs to other entities or entity collections that have a relationship to the group member entity.
    - user required string: A relationship to the user object
  - type required string: The type identifier of the group member entity (group-members).

Output

Output schema unknown

group_members_delete

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Removes a member from a group. This request only removes the relationship between the group and the user, it does not delete the user itself.

A group must always have at least one manager, and attempting to remove the only manager from a group will result in a 400 Bad Request response.

Permissions

A user can remove themselves as a member. Otherwise, only project managers can remove members.

Returns

If the request is successful, no content is returned.

osf.group_members_delete({
  "group_id": "",
  "user_id": ""
}, context)

Input

input object
- group_id required string: The unique identifier of the group.
- user_id required string: The unique identifier of the user.

Output

Output schema unknown

group_members_read

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Retrieves the details of a given group member.

Groups are collections of users that can be added to a project or several projects. Group members either have a manager or member role.

Returns

Returns a JSON object with a data key containing the representation of the requested contributor, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.group_members_read({
  "group_id": "",
  "user_id": ""
}, context)

Input

input object
- group_id required string: The unique identifier of the group.
- user_id required string: The unique identifier of the user.

Output

output object
- attributes object: The properties of the contributor entity.
  - email string: The unregistered user email. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
  - full_name string: The full name of the user, used for display on the OSF. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
  - role string (values: manager, member): The permission level of the group member. The default value is 'member'.
  - unregistered_member string: The assigned name of the group member if the member has not yet claimed their account.
- id string: The identifier of the group member entity. Member identifiers have the form {group_id}-{user_id}.
- links object: URLs to alternative representations of the group member entity.
  - self string: A link to the the canonical API endpoint for the group member.
- relationships required object: URLs to other entities or entity collections that have a relationship to the group member entity.
  - user required string: A relationship to the user object
- type required string: The type identifier of the group member entity (group-members).

group_members_partial_update

NOTE This feature is experimental and subject to change at any time. It may only be available on certain environments.

Updates a group member by setting the values of the attributes specified in the request body. Any unspecified attributes will be left unchanged.

Group members can be updated with either a PUT or PATCH request. Since this endpoint has no mandatory attributes, PUT and PATCH are functionally the same.

Permissions

Only group managers can update group membership.

Returns

Returns a JSON object with a data key containing the new representation of the updated contributor, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

If the given user is not already in the member list, a 404 Not Found error will be returned. A group must always have at least one manager, and any attempt to downgrade the permissions of a sole manager will result in a 400 Bad Request error.

osf.group_members_partial_update({
  "group_id": "",
  "user_id": "",
  "body": {
    "type": "",
    "relationships": {
      "user": ""
    }
  }
}, context)

Input

input object
- group_id required string: The unique identifier of the group.
- user_id required string: The unique identifier of the user.
- body required object
  - attributes object: The properties of the contributor entity.
    - email string: The unregistered user email. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
    - full_name string: The full name of the user, used for display on the OSF. Writeable when adding an unregistered member to your group, instead of an existing OSF user.
    - role string (values: manager, member): The permission level of the group member. The default value is 'member'.
    - unregistered_member string: The assigned name of the group member if the member has not yet claimed their account.
  - id string: The identifier of the group member entity. Member identifiers have the form {group_id}-{user_id}.
  - links object: URLs to alternative representations of the group member entity.
    - self string: A link to the the canonical API endpoint for the group member.
  - relationships required object: URLs to other entities or entity collections that have a relationship to the group member entity.
    - user required string: A relationship to the user object
  - type required string: The type identifier of the group member entity (group-members).

Output

Output schema unknown

institutions_list

A paginated list of all verified institutions.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 institutions. Each resource in the array is a separate institution object.

The links key contains a dictionary of links that can be used for pagination.

This request should never return an error.

Filtering

You can optionally request that the response only include institutions that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/institutions/?filter[id]=cos.

Institutions may be filtered by their id, name, and auth_url

You can learn more about advanced filtering features here.

osf.institutions_list(null, context)

Input

This action has no parameters

Output

output array
- items object
  - attributes object: The properties of the institution entity.
    - assets object: Assets belonging to a specific institution
      - logo string: Static path to the institution specific normal logo
      - logo_rounded string: Static path to the institution specific rounded logo
    - auth_url string: Url used to authenticate institution specific login.
    - description string: Description of the institution.
    - name string: Full name of the institution.
  - id string: The identifier of the institution entity.
  - links object: URLs to alternative representations of the institutions entity.
    - html string: A link to the detail page for the institution on the OSF.
    - self string: A link to the detail page for the institution.
  - relationships object: URLs to other entities or entity collections that have a relationship to the institution entity.
    - nodes string: A relationship to the nodes affiliated with the institution.
    - registrations string: A relationship to the registrations affiliated with the institution.
    - users string: A relationship to the users affiliated with the institution.
  - type string: The type identifier of the institution entity (institutions).

institutions_detail

Retrieves the details of an institution

Returns

Returns a JSON object with a data key containing the representation of the requested institution, if the request was successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.institutions_detail({
  "institution_id": ""
}, context)

Input

input object
- institution_id required string: The unique identifier of the institution you wish to retrieve.

Output

output array
- items object
  - attributes object: The properties of the institution entity.
    - assets object: Assets belonging to a specific institution
      - logo string: Static path to the institution specific normal logo
      - logo_rounded string: Static path to the institution specific rounded logo
    - auth_url string: Url used to authenticate institution specific login.
    - description string: Description of the institution.
    - name string: Full name of the institution.
  - id string: The identifier of the institution entity.
  - links object: URLs to alternative representations of the institutions entity.
    - html string: A link to the detail page for the institution on the OSF.
    - self string: A link to the detail page for the institution.
  - relationships object: URLs to other entities or entity collections that have a relationship to the institution entity.
    - nodes string: A relationship to the nodes affiliated with the institution.
    - registrations string: A relationship to the registrations affiliated with the institution.
    - users string: A relationship to the users affiliated with the institution.
  - type string: The type identifier of the institution entity (institutions).

institutions_node_list

A paginated list of all nodes affiliated with an institution.

Versioning

As of version 2.2, affiliated components (in addition to affiliated top-level projects) are returned from this endpoint.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 nodes. Each resource in the array is a separate nodes object.

The links key contains a dictionary of links that can be used for pagination.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

Filtering

You can optionally request that the response only include nodes that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/institutions/cos/nodes?filter[title]=science.

Nodes may be filtered by their id, title, description, public, tags, category, date_created, date_modified, root, parent, contributors, and preprint.

You can learn more about advanced filtering features here.

osf.institutions_node_list({
  "institution_id": ""
}, context)

Input

input object
- institution_id required string: The unique identifier of the institution you wish to retrieve.

Output

output array
- items object
  - attributes required object: The properties of the node entity.
    - category required string (values: analysis, communication, data, hypothesis, instrumentation, methods and measures, procedure, project, software, other): The category of the node, as selected by project contributors.
    - collection boolean: Whether or not this node represents a collection. This value should always be false. This field may be deprecated in future versions.
    - current_user_can_comment boolean: Whether or not the current user has permission to post comments on this node. Comments on nodes can be set to allow all users to comment (if public) or restricted to only allow comments from contributors.
    - current_user_permissions array: A list of strings representing the permissions for the current user on this node. Valid permissions are "admin", "read", and "write".
      - items string
    - date_created string: The time at which the node was created, as an iso8601 formatted timestamp.
    - date_modified string: The time at which the node was last modified, as an iso8601 formatted timestamp.
    - description string: The description of the node.
    - fork boolean: Whether or not this node represents a fork of another node.
    - forked_date string: If this node is a fork of another node, the time at which the node was created, as an iso8601 formatted timestamp.
    - node_license string: A dictionary containing the metadata (copyright year and holder) associated with the node license (required for certain license types).
    - preprint boolean: Whether or not the node contains supplemental material for a preprint.
    - public boolean: Whether or not the node is publicly visible. This field is only editable by project administrators.
    - registration boolean: Whether or not the node represents a registration. This value should always be false. This field may be deprecated in future versions.
    - tags array: A list of strings that describe this node, as entered by project contributors.
      - items string
    - template_from string: The unique ID of the node from which this node was templated, if this node was created from a template.
    - title required string: The title of the node.
    - wiki_enabled boolean: Whether or not the node has its wiki enabled.
  - id string: The unique identifier of the node entity.
  - links object: URLs to alternative representations of the node entity.
    - html string: A link to the node's page on the OSF.
    - self string: A link to the canonical API endpoint of this node.
  - relationships object: URLs to other entities or entity collections that have a relationship to the node entity.
    - affiliated_institutions string: A link to the list of institutions this node is affiliated with.
    - children string: A link to the list of this node's children (components).
    - citation string: A link to the citation details of this node.
    - comments string: A link to the list of comments on this node.
    - contributors string: A link to the list of contributors on this node.
    - draft_registrations string: A link to the list of registrations that have been initiated from this node and are still in a draft state.
    - files string: A link to the list of storage providers that have been enabled on this node.
    - forked_from string: A link to the node which this node was forked from, if this node is a fork.
    - forks string: A link to the list of nodes that are forks of this node.
    - groups string: A link to the list of groups that have permissions to the node.
    - identifiers string: A link to the list of identifiers for this node (i.e. DOI identifiers).
    - license string: A link to the license that has been applied to this node.
    - linked_nodes string: A link to the list of nodes that are linked to the current node.
    - logs string: A link to the list of log actions pertaining to this node.
    - node_links string: A link to the list of nodes that are linked to the current node. This field has been deprecated as of verson 2.1; use the linked_nodes link instead.
    - parent string: A link to the node that is the direct parent of the current node, if the current node is a child node.
    - preprints string: A link to the list of preprints for which this node contains supplemental materials.
    - registrations string: A link to the list of registrations that have been created from this node.
    - root string: A link to the node that is the top-level parent of the current node. If the current node is the top-level node, the root is the current node.
    - template_node string: A link to the node that the current node was templated from, if the current node was created from a template.
    - view_only_links string: A link to the list of view only links that have been created for this node.
    - wikis string: A link to the list of wiki pages for this node.
  - type required string: The type identifier of the node entity (nodes).

institutions_registration_list

A paginated list of all registrations affiliated with an institution.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 registrations. Each resource in the array is a separate users object.

The links key contains a dictionary of links that can be used for pagination.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

Filtering

You can optionally request that the response only include registrations that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/institutions/cos/registrations?filter[title]=science.

Registrations may be filtered by their id, title, description, public, tags, category, date_created, date_modified, root, parent, contributors, and preprint

osf.institutions_registration_list({
  "institution_id": ""
}, context)

Input

input object
- institution_id required string: The unique identifier of the institution you wish to retrieve.

Output

Output schema unknown

institutions_users_list

A paginated list of all users affiliated with an institution.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 users. Each resource in the array is a separate users object.

The links key contains a dictionary of links that can be used for pagination.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

Filtering

You can optionally request that the response only include users that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/institutions/cos/users?filter[family_name]=Nosek.

Users may be filtered by their id, full_name, given_name, middle_names, and family_name

You can learn more about advanced filtering features here.

osf.institutions_users_list({
  "institution_id": ""
}, context)

Input

input object
- institution_id required string: The unique identifier of the institution you wish to retrieve.

Output

output array
- items object
  - attributes required object: The properties of the user entity.
    - active required boolean: Whether or not the user is an active user.
    - date_registered required string: The time at which the user registered their account, as an iso8601 formatted timestamp.
    - family_name string: The family name of the user, used for bibliographic citations.
    - full_name required string: The full name of the user, used for display on the OSF.
    - given_name string: The given name of the user, used for bibliographic citations.
    - locale string: The user's locale, e.g. 'en_US'.
    - middle_names string: The middle names of the user, used for bibliographic citations.
    - social object: The social fields associated with a user.
      - academiaProfileID string: The academiaProfileID for the given user.
      - baiduScholar string: The baiduScholar for the given user.
      - github array: The github usernames for the given user.
        items string
      - impactStory string: The impactStory for the given user.
      - linkedIn array: The linkedIn profiles for the given user.
        items string
      - orcid string: The orcid for the given user.
      - profileWebsites array: The profileWebsites for the given user.
        items string
      - researchGate string: The researchGate for the given user.
      - researcherId string: The researcherId for the given user.
      - scholar string: The google scholar for the given user.
      - ssrn string: The ssrn for the given user.
      - twitter array: The twitter handles for the given user.
        items string
    - suffix string: The suffix of the user, used for bibliographic citations.
    - timezone string: The user's timezone, e.g. 'Etc/UTC'.
  - id required string: The unique identifier of the user entity.
  - links required object: URLs to alternative representations of the user entity.
    - html string: A link to the user's profile page on the OSF.
    - profile_image string: A link to the user's profile image.
  - relationships required object: URLs to other entities or entity collections that have a relationship to the user entity.
    - default_region string: The storage region where the user's files will be stored by default.
    - groups string: A link to the list of groups that a user belongs to.
    - institutions string: A link to the list of institutions the user is affiliated with.
    - nodes string: A link to the list of nodes the user is a contributor to.
  - type required string: The type identifier of the user entity (users).

licenses_read

Retrieves the details of a license.

Returns

Returns a JSON object with a data key containing the representation of the requested license, if the request is successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.licenses_read({
  "license_id": ""
}, context)

Input

input object
- license_id required string: The unique identifier of the license.

Output

output object
- attributes object: The properties of the license.
  - name string: Name of the license.
  - required_fields array: Fields required for this license (provided to help front-end validators). Maps to properties on the NodeLicense model.
    - items string: Individual fields required by this license.
  - text string: Full text of the license.
- id string: The identifier of the license.
- links object: URLs to alternative representations of the license.
  - self string: A link to the detail page for the license.
- type string: The type identifier of the license (license).

license_list

A paginated list of licenses. The returned licenses are sorted by their name.

Returns

Returns a JSON object containing data and links keys.

The data key contains an array of 10 licenses. Each resource in the array is a separate license object and contains the full representation of the license, meaning additional requests to a license's detail view are not necessary.

The links key contains a dictionary of links that can be used for pagination.

This request should never return an error.

Filtering

You can optionally request that the response only include licenses that match your filters by utilizing the filter query parameter, e.g. https://api.osf.io/v2/licenses/?filter[name]=apache.

Licenses may be filtered by their id, and name.

You can learn more about advanced filtering features here.

osf.license_list(null, context)

Input

This action has no parameters

Output

output array
- items object
  - attributes object: The properties of the license.
    - name string: Name of the license.
    - required_fields array: Fields required for this license (provided to help front-end validators). Maps to properties on the NodeLicense model.
      - items string: Individual fields required by this license.
    - text string: Full text of the license.
  - id string: The identifier of the license.
  - links object: URLs to alternative representations of the license.
    - self string: A link to the detail page for the license.
  - type string: The type identifier of the license (license).

logs_read

Retrieves the details of a log.

A log is permanent immutable record of a node's history. A log is created when a user performs one of many actions. See the actions section for more details.

Returns

Returns a JSON object with a data key containing the representation of the requested log, if the request was successful.

If the request is unsuccessful, an errors key containing information about the failure will be returned. Refer to the list of error codes to understand why this request may have failed.

osf.logs_read({
  "log_id": ""
}, context)

Input

input object
- log_id required string: The unique identifier of the log you wish to retrieve.

Output

output object
- attributes required object: The properties of the log.
  - action required string: The type of action performed on the OSF. See actions section for full list of possible actions.
  - date required string: The date and time at which the log was created, as an iso8601 formatted timestamp.
  - params object: The type of action performed on the OSF. See description for full list of possible actions.
    - addon string: The addon associated with the connected node.
    - anonymous_link boolean: The view only link added to the node was anonymous.
    - bucket string: The Amazon s3 bucket connected to the connected node.
    - citation_name string: Name of citation associated with the connected node.
    - contributors string: List of contributors on the connected node involved in the action represented by this node log.
    - data_set string: The dataset associated with the connected node.
    - destination string: A dictionary with information about the destination for the move of the item on the node associated with this log. Details include the path, url, addon, node_url and node_title.
    - figshare_title string: Title of the fighshare project associated with this node log
    - file string: Dictionary with information about the file involved with the log.
    - filename string: Filename for the file associated with the log.
    - folder string: Folder associated with the log.
    - folder_name string: Name of the folder associated with the log.
    - forward_url string: URL

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@datafire/osf

Installation and Usage

Description

https://api.osf.io/v2/

Actions

base_read

Returns

Input

Output

logs_actions

Input

Output

addons_list

Returns

Input

Output

citations_styles_list

Returns

Filtering

Input

Output

citations_styles_read

Returns

Input

Output

comments_delete

Returns

Input

Output

comments_read

Returns

Input

Output

comments_put

Returns

Input

Output

files_detail

Returns

Waterbutler API actions

Download (files)

Create Subfolder (folders)

Upload New File (folders)

Update Existing File (file)

Rename (files, folders)

Move & Copy (files, folders)

Input

Output

files_patch

Returns

Input

Output

files_versions

Returns

Input

Output

files_version_detail

Returns

Input

Output

groups_list

Returns

Filtering

Input

Output

groups

Required

Returns

Input

Output

groups_delete

Permissions

Returns

Input