openapi-directory

Version:

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

github.com/httptoolkit/openapi-directory-js

1 lines • 683 kB

JSON

{"openapi":"3.0.0","info":{"contact":{"email":"support@osf.io","name":"OSF","url":"https://osf.io/support","x-twitter":"OSFramework"},"description":"## https://api.osf.io/v2/","license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"title":"OSF APIv2 Documentation","version":"2.0","x-apisguru-categories":["open_data"],"x-logo":{"backgroundColor":"transparent","url":"https://cdn.cos.io/media/images/cos_center_logo_small.original.png"},"x-origin":[{"format":"swagger","url":"http://developer.osf.io/swagger.json","version":"2.0"}],"x-providerName":"osf.io"},"tags":[{"description":"Welcome to the Open Science Framework API. With this API you can access users, projects, components, logs, and files from the [Open Science Framework](https://osf.io/). The Open Science Framework (OSF) is a free, open-source service maintained by the [Center for Open Science](http://cos.io/).\n\nThe OSF serves as a repository and archive for study designs, materials, data, manuscripts, or anything else associated with your research during the research process. Every project and file on the OSF has a permanent unique identifier, and every registration (a permanent, time-stamped version of your projects and files) can be assigned a DOI. You can use the OSF to measure your impact by monitoring the traffic to projects and files you make public. With the OSF you have full control of what parts of your research are public and what remains private.","name":"Introduction","x-traitTag":true},{"description":"The OSF API generally conforms to the [JSON-API v1.0 spec](http://jsonapi.org/format/1.0/). Where exceptions exist, they will be noted. Each endpoint will have its own documentation, but there are some general principles.\n\nNote: Assume undocumented routes/features/fields are unstable.\n\n#### Canonical URLs\n\nAll canonical URLs have trailing slashes. A request to an endpoint without a trailing slash will result in a **301 Redirect** to the canonical URL. There are some exceptions when working with the Files API, so if a URL in a response does not have a slash, do not append one.\n\n#### Plurals\n\nEndpoints are always pluralized. `/users/`, not `/user/`, `/nodes/`, not `/node/`.\n\nThe only exception are the node and preprint citation endpoints, which are `/citation/`, not `/citations/`.\n\n#### Common Actions\n\nEvery endpoint in the OSF API responds to `GET`, `HEAD`, and `OPTION` requests.\n\nYou must have adequate permissions to interact with any endpoint. Unauthorized use will result in **401 Unauthorized** or **403 Forbidden** responses.\n\nUse `HEAD` to probe an endpoint and make sure your headers are well-formed.\n\nA `GET` request will return a representation of the entity or entity collection referenced by the endpoint.\n\nAn `OPTIONS` request will return a JSON object that describes the endpoint, including the name, a description, the acceptable request formats, the allowed response formats, and any actions available via the endpoint.\n\n#### Testing\n\n##### Testing Server\n\nThe test-* subdomains of the osf are intended to match, at any given time, the current production environment of the Open Science Framework.\n\nWe have staging servers that will have newer features, including newer API features, that aren't ready for production. However, because those servers are subject to the whims of QA and whichever group needs to do specific testing, they aren't particular stable for API developers.\n\nThe test servers linked below are primarily for developing your API application on a stable system.\n\nhttps://test.osf.io/\n\nhttps://api.test.osf.io/v2/\n\n##### Ephemerality Notice\n\nExpect the server to be down from time to time while we update software, and don't expect that anything you create on here to exist long-term.\n\nWhile this is more stable than a staging server, we won't necessarily run data migrations if anything major happens to our database schema, so we may clear out the data on the test servers periodically.","name":"General Usage","x-traitTag":true},{"description":"#### Token Auth\n\nTo use a Personal Access Token (PAT), make an `Authorization` header with the contents `Bearer <token>` as shown in the example below, replacing `<token>` with your token.\n\n\n curl -X \"GET\" \"https://api.osf.io/v2/users/me/\" \\\n -H \"Authorization: Bearer <token>\"\n\n\nTo make a Personal Access Token, visit your OSF settings page (either on the [OSF](https://osf.io/settings/tokens/) or our [testing server](https://test.osf.io/settings/tokens/)) to create one. You can limit the scope of the token, but remember that it has access to all of the information that you do within the limits of the scope, so be careful with your tokens.\n\n#### OAuth\n\nThe OSF allows third-party web applications to connect to the OSF on behalf of other users via the OAuth 2.0 web application flow.\n\nYou can add a developer application from the OSF settings page (either on the [OSF](https://osf.io/settings/tokens/) or our [testing server](https://test.osf.io/settings/tokens/)).\n\nWe will be adding narrative documentation for handling OAuth flows, but for now, if you're familiar with OAuth, you can check out the [CAS overlay documentation](https://github.com/CenterForOpenScience/cas-overlay#web-server-authorization) for options.\n\n#### When to use Token Auth\nYou should use Token Auth if:\n+ You want to use the API to interact with your own OSF data\n+ You have scripts to push or extract data from your OSF account\n+ You want to use the API to programmatically automate certain actions in your own OSF account\n\n#### When to use OAuth\nYou should use OAuth if:\n+ You are requesting access to other people's OSF accounts/data to push or extract data on their behalf\n+ You currently ask people for their PAT to request resources on their behalf","name":"Authentication","x-traitTag":true},{"description":"All entity collection endpoints respond to the `page` query parameter as described in the [JSON-API spec](http://jsonapi.org/format/#fetching-pagination).\n\nHowever, links to the first, last, previous, and next pages of results are provided in the `links` key of the response, and you are encouraged to use those rather than adding query parameters by hand.\n\nIf there are only enough results to fill one page, the `first`, `last`, `prev`, and `next` links will be null.\n\n#### Versioning\n\nAs of version `2.3`, pagination links conform to the JSON API specification. Meta information was pulled out of the `links` object and placed in a top-level `meta` object.\n\nThe `meta` key contains the total number of entities available, as well as the current number of results displayed per page.","name":"Pagination","x-traitTag":true},{"description":"For any additions to the api (new fields, routes, methods, or relationships), those additions will be added simultaneously to all versions. For any breaking changes and deletions, a new API version will be released. Requesting the base API takes the most compatible version of the API, not the one with the latest changes. Note that, in the case of the OSF model changing, legacy API functionality *may* break. We try very hard not to let this happen, but sometimes it's unavoidable.\n\nVersioning can be specified in three different ways:\n\n#### URL Path Versioning\n\n+ `/v2/` or `/v3/`\n\n+ A version specified via the URL path is a **required** part of the URL.\n\n+ Only a major version can be specified via the URL path, i.e. `/v2.0.6/` is invalid, additionally, paths such as `/v2.0/` are invalid.\n\n+ If the default version of the API is within the major version specified in the URL path, the default version will be applied (i.e. if the default version is `2.3` and the URL path is `/v2/`, then version returned will be `2.3`).\n\n+ If the default version of the API is not within the major version specified in the URL path, the URL path version will be applied (i.e. if the default version is `3.0` and the URL path is `/v2/`, then the version returned will be `2.0`)\n\n#### Query Parameter Versioning\n\n+ `/v2/nodes/?version=2.1.6`\n\n+ Pinning to a specific version via a query parameter is **optional**.\n\n+ A specific version (major, minor, or patch) for a single request can be specified via the `version` query parameter, as long as it is an allowed version.\n\n+ If the version specified in the query parameter does not fall within the same major version specified in the URL path, i.e `/v2/nodes/?version=3.1.4` a 409 Conflict response will be returned.\n\n#### Header Versioning\n\n+ `Accept-Header=application/vnd.api+json;version=3.0.1`\n\n+ Pinning to a specific version via request header is **optional**.\n\n+ A specific version (major, minor, or patch) for a single request can be specified via the `Accept Header` of the request, as long as it is an allowed version.\n\n+ If the version specified in the header does not fall within the same major version specified in the URL path a 409 Conflict response will be returned.\n\n+ If both a header version and query parameter version are specified, the versions must match exactly or a 409 Conflict response will be returned (i.e. one does not take precedence over the other).","name":"Versioning","x-traitTag":true},{"description":"Entity collections can be filtered by adding a query parameter in the form:\n\n    `filter[<fieldname>]=<matching information>`\n\nString queries are filtered using substring matching. For example, if you were trying to find [Lise Meitner](http://en.wikipedia.org/wiki/Lise_Meitner):\n\n    `/users/?filter[full_name]=meitn`\n\nYou can filter on multiple fields, or the same field in different ways, by &-ing the query parameters together.\n\n    `/users/?filter[full_name]=lise&filter[family_name]=mei`\n\nBoolean fields should be queried with `true` or `false`.\n\n    `/nodes/?filter[registered]=true`\n\nYou can request multiple resources by filtering on id and placing comma-separated values in your query parameter.\n\n    `/nodes/?filter[id]=aegu6,me23a`\n\nYou can filter with case-sensitivity or case-insensitivity by using `contains` and `icontains`, respectively.\n\n    `/nodes/?filter[tags][icontains]=help`\n\nYou can also filter on comparable, ordered fields, including datetimes and integers.\n\nYou can filter using comparisons by using the follow syntax:\n\n    `?filter[date_modified][gte]=2014-10-10`\n\nValid comparison operators include:\n+ `[gte]` = greater than or equal\n+ `[gt]` = greater than\n+ `[lte]` = less than or equal\n+ `[lt]` = less than\n+ `[eq]` = equals\n+ `[ne]` = does not equal\n\nThese comparison filters work for dates and integers. For example, you can use two comparison filters to specify\n\n    `[date_modified][gte]=2014-10-10&[date_modified][lt]=2014-11-10`\n\nor exclude\n\n    `[date_created][lt]=2014-10-10&[date_created][gt]=2014-11-10`\n\na range of dates from your search. Note that the dates must be in YYYY-MM-DD format.","name":"Filtering","x-traitTag":true},{"description":"All endpoints respond to the `fields` query parameter as described in the [JSON-API spec](http://jsonapi.org/format/#fetching-sparse-fieldsets).\n\n\nFrom the specification:\n\n\n<blockquote>\n A client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter.\n The value of the fields parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned.\n If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.\n</blockquote>\n\n\n#### Basic Usage\n\n\nWhen making a request to an endpoint that returns a serialized object of some `type`, you can specify `fields[<type>]=<comma,separated,list,of,fields>` to receive a subset of the object's fields in the response.\n\n\nFor example, the request below will serialize only the `title` attribute and `children` relationship for each node in the response.\n\n\nhttps://api.osf.io/v2/nodes/?fields[nodes]=title,children\n\n\nSparse fieldsets can be used to restrict both attribute and relationship fields.\nNote that top-level objects (such as `type`, `id`, `attributes`, `relationships`, and `links`) will always be serialized and cannot be excluded.\n\n\n#### Advanced Usage\n\n\nSparse fieldsets can be used to restrict any entity returned in the response.\n\n\nFor example, the request below will serialize only the `full_name` attribute for each user (auto-embedded by the `embed=contributors` query parameter), and the `title` attribute for each node.\n\n\nhttps://api.osf.io/v2/nodes/?fields[nodes]=title,contributors&embed=contributors&fields[users]=full_name\n\n\nAny field specified in another query parameters used by the serializer (e.g. `embed`) must also be included in the sparse fieldset.\nFor example, fields that are being embedded on the sparse type (e.g. `nodes`) must also be included in `fields[<type>]` when using embeds, or the embed will be invalid.\n\n\nA request to embed contributors and restrict nodes to only return the `title` attribute should have the form:\n\n\nhttps://api.osf.io/v2/nodes/?embed=contributors&fields[nodes]=title,contributors\n\n\n**NOT**\n\n\nhttps://api.osf.io/v2/nodes/?embed=contributors&fields[nodes]=title\n","name":"Sparse Fieldsets","x-traitTag":true},{"description":"All related resources that appear in the `relationships` attribute are embeddable, meaning it is possible to fetch a node and its contributors in a single request by adding a query parameter like:\n\n    `/nodes/?embed=contributors`\n\nThe embedded results will have the following structure:\n\n    `{relationship_name}: {full_embedded_response}`\n\nWhere `full_embedded_response` means the full API response resulting from a **GET** request to the `href` link of the corresponding related resource.\n\nThis means if there are no errors in processing the embedded request the response will have the format:\n\n    `data: {response}`\n\nAnd if there are errors processing the embedded request the response will have the format:\n\n    `errors: {errors}`\n\nMultiple embeds can be achieved with multiple query parameters separated by \"&\".\n\n    `/nodes/?embed=contributors&embed=comments`\n\nSome endpoints are automatically embedded, such as the [node contributors](#operation/nodes_contributors_list) endpoint, which automatically embeds user information.","name":"Embedding","x-traitTag":true},{"description":"All related resources that appear in the `relationships` attribute can have a count associated with them, this allows you to see number of resources associated with a queried object before you query them. The count will appear in the `count` variable of the field’s `links.related.meta` object.\n\nTo view the count of objects in the relationship field add the query parameter `?related_counts=<field_name>`, for multiple fields use a comma separated list like `?related_counts=<field_name1>,<field_name2>` for all related fields use `?related_counts=True`.\n\n\nFor example using the the url `/v2/users/<user_id>/?related_counts=nodes` for a user with 4 nodes will return the following for the node field of the user object.\n\n GET /v2/users/<user_id>/?related_counts=nodes/\n \"nodes\": {\n \"links\": {\n \"related\": {\n \"href\": \"https://api.osf.io/v2/users/<user_id>/nodes/\",\n \"meta\": {\n \"count\": 4\n }\n }\n }\n },","name":"Related Counts","x-traitTag":true},{"description":"## Attribute Validation\n\nEndpoints that allow creation or modification of entities generally limit updates to certain attributes of the entity.\n\nIf you attempt to set an attribute that does not permit updates (such as a `date_created` timestamp), the API will silently ignore that attribute.\n\nThis will not affect the response from the API: if the request would have succeeded without the updated attribute, it will still report as successful. Likewise, if the request would have failed without the attribute update, the API will still report a failure.\n\nTypoed or non-existent attributes will behave the same as non-updatable attributes and will be silently ignored. If a request is not working the way you expect, make sure to double check your spelling.\n\n## Create/Update Requests\n\n#### Formatting POST/PUT/PATCH Request Bodies\n\nThe OSF API follows the JSON-API spec for [create and update requests](http://jsonapi.org/format/1.0/#crud). This means all request bodies must be wrapped with some metadata.\n\nEach request body must be an object with a `data` key containing at least a `type` member. The value of the `type` member must agree with the `type` of the entities represented by the endpoint. If not, a **409 Conflict** will be returned.\n\nThe request should also contain an `attributes` member with an object containing the key-value pairs to be created/updated.\n\n**PUT/PATCH** requests must also have an `id` key that matches the ID part of the endpoint you are making a request to. If the `id` key does not match the ID part of the URL path, a **409 Conflict** error will be returned.\n\n#### Creating a Node via POST Example\n\n\n POST /v2/nodes/\n {\n \"data\": {\n \"type\": \"nodes\",\n \"attributes\": {\n \"title\" : \"A Phylogenetic Tree of Famous Internet Cats\",\n \"category\" : \"project\",\n \"description\" : \"How closely related are Grumpy Cat and C.H. Cheezburger? Is memefulness inheritable?\"\n }\n }\n }\n\n\n#### Updating a User via PUT Example\n\n\n PUT /v2/users/me/\n {\n \"data\": {\n \"id\": \"3rqxc\",\n \"type\": \"users\",\n \"attributes\": {\n \"full_name\" : \"Henrietta Swan Leavitt\",\n \"given_name\" : \"Henrietta\",\n \"middle_names\" : \"Swan\",\n \"family_name\" : \"Leavitt\"\n }\n }\n }\n\n\n**Note:** If you PUT/PATCH to the `/users/me/` endpoint, you must still provide your full user id in the `id` field of the request. We do not support using the `me` alias in request bodies at this time.\n\n#### PUT vs. PATCH\n\nFor most endpoints that support updates via **PUT** requests, we also allow **PATCH** updates.\n\n**PUT** requests require all mandatory attributes to be set, even if their value is unchanged. **PATCH** requests may omit mandatory attributes, whose value will be unchanged.","name":"Request Formatting","x-traitTag":true},{"description":"## Errors\n\nWhen a request fails for any reason, the OSF API will return an appropriate HTTP response code and include a descriptive error in the body of the response.\n\nThe response body will be a JSON object with a key, `errors`, pointing to an array of error objects.\n\nIn general, these error objects will consist of a `detail` key with a detailed error message and a `source` object that may contain a field `pointer` that is a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to the error-causing attribute.\n\nThe `error` objects may include additional information in accordance with the [JSON-API error spec](http://jsonapi.org/format/1.0/#error-objects).\n\n#### Example\n\nAn error response from an incorrect create node request:\n\n\n {\n \"errors\": [\n {\n \"source\": {\n \"pointer\": \"/data/attributes/category\"\n },\n \"detail\": \"This field is required.\"\n },\n {\n \"source\": {\n \"pointer\": \"/data/type\"\n },\n \"detail\": \"This field may not be null.\"\n },\n {\n \"source\": {\n \"pointer\": \"/data/attributes/title\"\n },\n \"detail\": \"This field is required.\"\n }\n ]\n }\n\n\n## Error Codes\n\nThe OSF API uses conventional HTTP response codes to indicate the success or failure of an API request.\n\nIn general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, invalid authentication credentials were provided, etc.), and codes in the `5xx` range indicate an error with our API servers (these are rare, and if they occur consistently, should be [reported](mailto:support@osf.io)).\n\n`200` **OK**\n\nThe request was successful and everything worked as expected.\n\n`201` **Created**\n\nThe request was successful and a new resource was created. The newly created resource can be referenced by the ID returned in the response.\n\n`204` **No Content**\n\nThe request was sucessful but does not need to return an entity-body.\n\n`400` **Bad Request**\n\nThe request was unacceptable, often due to a missing required parameter or malformed data.\n\n`401` **Unauthorized**\n\nThe request requires user authentication, which was not provided.\n\n`403` **Forbidden**\n\nThe request was understood but not fulfilled, most likely due to invalid permissions.\n\n`404` **Not Found**\n\nThe requested resource does not exist.\n\n`405` **Method Not Allowed**\n\nThe method specified in the request is not allowed for the resource.\n\n`409` **Conflict**\n\nThe request could not be completed due to a conflict with the current state of the resource or within the request data.\n\n`410` **Gone**\n\nThe requested resource is no longer available, most likely because it was deleted.\n\n`429` **Too Many Requests**\n\nThe user has sent too many requests in a given amount of time.\n\nWait at least the amount of time specified in the `Retry-After` header of the response before sending another request.\n\nAuthenticated requests have a rate limit of 10,000/day.\n\nUnauthenticated requests have a rate limit of 100/hour.\n\n`5xx` **Server Errors**\n\nThe API server encountered an unexpected error.","name":"Errors & Error Codes","x-traitTag":true},{"description":"## Entities\n\nAn entity is a single resource that has been retrieved from the API, usually from an endpoint with the entity's ID as the final path part. A successful response from an entity request will be a JSON object with a top level `data` key pointing to a sub-object with the following members:\n\n#### ID\n\nThe identifier for the entity. This **MUST** be included with all PUT and PATCH requests.\n\n#### Type\n\nThe type identifier of this entity. This **MUST** be included with all create and update requests.\n\n#### Attributes\n\nThe properties of the entity. Names, descriptions, etc.\n\n#### Relationships\n\nRelationships are URLs to other entities or entity collections that have a relationship to the entity.\n\nFor example, the node entity provides a `contributors` relationship that points to the endpoint to retrieve all contributors to that node. It is recommended to use these links rather than to filter general entity collection endpoints by IDs. They'll be faster, easier, and less error-prone.\n\nGenerally a relationship will have the following structure:\n\n\n {relationship_name}: {\n \"links\": {\n \"related\": {\n \"href\": {url_to_related_entity_or_entity_collection},\n \"meta\": {}\n }\n }\n }\n\n\nIf there are no related entities, `href` will be null.\n\n#### Embeds\n\nPlease see the [embedding](#tag/Embedding) documentation.\n\n#### Links\n\nLinks are urls to alternative representations of the entity or actions that may be performed on the entity.\n\nMost entities will provide a `self` link that is the canonical endpoint for the entity where update and delete requests should be sent. Most entities will also provide an `html` link that directs to the entity's page on the Open Science Framework.\n\n## Entity Collections\n\nEntity collection endpoints return a list of entities and an additional data structure with pagination links, such as `next`, `prev`, `first`, and `last`.\n\nThe OSF API limits all entity collection responses to a maximum of 10 entities.\n\nThe response object has two keys:\n\n#### Data\n\nThe `data` key is an array of entities that match the query.\n\nEach entity in the array is the same representation that is returned from that entity's `self` link, meaning that refetching the entity is unnecessary.\n\n#### Links\n\nThe `links` key contains pagination information, including links to the previous, next, first, and last pages of results.\n\nThe `meta` key contains the total number of entities available, as well as the current number of results displayed per page.\n\nIf there are only enough results to fill one page, the `first`, `last`, `prev`, and `next` values will be null.","name":"Entities & Entity Collections","x-traitTag":true},{"description":"#### [osfclient](https://github.com/osfclient/osfclient)\nA python library and command-line client for file storage on the OSF.\n#### [OSFR](https://github.com/CenterForOpenScience/osfr)\nAn R package to interface with the OSF.","name":"External Libraries","x-traitTag":true},{"description":"\n\n#### 2.13\n\n+ Resource types for Resource Object Identifiers have been corrected for these relationsips:\n + `nodes.linked_nodes` (was `type: linked_nodes`, now: `type: nodes`)\n + `nodes.linked_registrations` (was `type: linked_registrations`, now: `type: registrations`)\n + `registrations.linked_nodes` (was `type: linked_nodes`, now: `type: nodes`)\n + `registrations.linked_registrations` (was `type: linked_registrations`, now: `type: registrations`)\n + `collections.linked_nodes` (was `type: linked_nodes`, now: `type: nodes`)\n + `collections.linked_registrations` (was `type: linked_registrations`, now: `type: registrations`)\n + `collections.linked_preprints` (was `type: linked_preprints`, now: `type: preprints`)\n + `preprints.node` (was `type: linked_preprint_nodes`, now: `type: nodes`)\n\n\n#### 2.12\n\n+ DELETE requests to a node detail will also delete all the node's subcomponents.\n\n#### 2.11\n\n+ Only return the permissions explicitly assigned to the current user in `current_user_permissions`.\n + No longer automatically return `read` for all public nodes.\n\n\n#### 2.10\n\n+ Return and require lists for the following `social` fields:\n + `github`\n + `twitter`\n + `linkedIn`\n + `profileWebsites`\n\n\n#### 2.9\n\n+ Return `null` for all empty relationships instead of ommitting them entirely.\n\n+ Deprecate the `metaschemas/registrations` endpoint in favor of `schemas/registrations`.\n\n#### 2.8\n\n+ Deprecate the `preprint_providers` endpoint in favor of `providers/preprints`.\n\n+ /data/relationships/wikis not shown in node data when the wiki is disabled for that project/component.\n\n#### 2.7\n\n+ Require `type` and `id` for all PATCH requests.\n\n#### 2.6\n\n+ Deprecate the [**Taxonomy List**](#tag/Taxonomies) endpoint.\n\n#### 2.5\n\n+ Deprecate the `subjects_acceptable` field in the **Preprint Provider** serializer.\n\n#### 2.4\n\n+ Deprecate the `parents` field in the **Taxonomies** serializer.\n\n+ Deprecate the following fields in the **Preprint Provider** serializer:\n + `social_facebook`, `social_instagram`, and `social_twitter`\n + `banner_path`, `logo_path`, and `header_text`\n + `email_contact`\n\n\n#### 2.3\n\n+ Handle merged users more correctly on `/v2/users/`.\n\n#### 2.2\n\n+ Modify institution nodes list so that affiliated components are also returned from `/v2/institutions/<id>/nodes/`.\n\n+ Ensure all existing date fields are standardized on UTC.\n\n#### 2.1\n\n+ Pagination links conform to JSON API specification, i.e. `meta` information was pulled out of the `links` object and placed in a top-level `meta` object.\n\n+ Deprecate the `node_links` field in the **Node** and **Registration** serializers in favor of `linked_nodes` and `linked_registrations`.","name":"Changelog","x-traitTag":true}],"paths":{"/":{"get":{"description":"Welcome to the Open Science Framework API. With this API you can access users, projects, components, logs, and files from the [Open Science Framework](https://osf.io/). The Open Science Framework (OSF) is a free, open-source service maintained by the [Center for Open Science](http://cos.io/).\n\n#### Returns\n\nA JSON object with `meta` and `links` keys.\n\nThe `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.\n\nThe `links` key contains links to the following entity collections: [addons](#tag/Addons), [collections](), [institutions](#tag/Institutions), [licenses](#tag/Licenses), [metaschemas](#tag/Metaschemas), [nodes](#tag/Nodes), [registrations](#tag/Registrations), [users](#tag/Users)","operationId":"base_read","responses":{"200":{"description":"OK"}},"summary":"Root","tags":["Base"]}},"/actions/":{"get":{"description":"A log can have one of many actions. The complete list of loggable actions (in the format {identifier}: {description}) is as follows:\n\n* `project_created`: A Node is created\n\n* `project_registered`: A Node is registered\n\n* `project_deleted`: A Node is deleted\n---\n\n* `created_from`: A Node is created using an existing Node as a template\n\n* `pointer_created`: A Pointer is created\n\n* `pointer_forked`: A Pointer is forked\n\n* `pointer_removed`: A Pointer is removed\n\n* `node_removed`: A component is deleted\n\n* `node_forked`: A Node is forked\n---\n\n* `made_public`: A Node is made public\n\n* `made_private`: A Node is made private\n\n* `tag_added`: A tag is added to a Node\n\n* `tag_removed`: A tag is removed from a Node\n\n* `edit_title`: A Node's title is changed\n\n* `edit_description`: A Node's description is changed\n\n* `updated_fields`: One or more of a Node's fields are changed\n\n* `external_ids_added`: An external identifier is added to a Node (e.g. the DOI)\n---\n\n* `view_only_link_added`: A view-only link was added to a Node\n\n* `view_only_link_removed`: A view-only link was removed from a Node\n\n---\n\n* `contributor_added`: A Contributor is added to a Node\n\n* `contributor_removed`: A Contributor is removed from a Node\n\n* `contributors_reordered`: A Contributor's position in a Node's bibliography is changed\n\n* `permissions_updated`: A Contributor`s permissions on a Node are changed\n\n* `made_contributor_visible`: A Contributor is made bibliographically visible on a Node\n\n* `made_contributor_invisible`: A Contributor is made bibliographically invisible on a Node\n\n---\n\n* `wiki_updated`: A Node's wiki is updated\n\n* `wiki_deleted`: A Node's wiki is deleted\n\n* `wiki_renamed`: A Node's wiki is renamed\n\n* `made_wiki_public`: A Node's wiki is made public\n\n* `made_wiki_private`: A Node's wiki is made private\n\n---\n\n* `addon_added`: An add-on is linked to a Node\n\n* `addon_removed`: An add-on is unlinked from a Node\n\n* `addon_file_moved`: A File in a Node's linked add-on is moved\n\n* `addon_file_copied`: A File in a Node's linked add-on is copied\n\n* `addon_file_renamed`: A File in a Node's linked add-on is renamed\n---\n\n* `node_authorized`: An addon is authorized for a project\n\n* `node_deauthorized`: An addon is deauthorized for a project\n---\n\n* `folder_created`: A Folder is created in a Node's linked add-on\n\n* `file_added`: A File is added to a Node's linked add-on\n\n* `file_updated`: A File is updated on a Node's linked add-on\n\n* `file_removed`: A File is removed from a Node's linked add-on\n\n* `file_restored`: A File is restored in a Node's linked add-on\n\n---\n\n* `comment_added`: A Comment is added to some item\n\n* `comment_removed`: A Comment is removed from some item\n\n* `comment_updated`: A Comment is updated on some item\n\n---\n\n* `embargo_initiated`: An embargoed Registration is proposed on a Node\n\n* `embargo_approved`: A proposed Embargo of a Node is approved\n\n* `embargo_cancelled`: A proposed Embargo of a Node is cancelled\n\n* `embargo_completed`: A proposed Embargo of a Node is completed\n---\n\n* `retraction_initiated`: A Withdrawal of a Registration is proposed\n\n* `retraction_approved`: A Withdrawal of a Registration is approved\n\n* `retraction_cancelled`: A Withdrawal of a Registration is cancelled\n---\n\n* `registration_initiated`: A Registration of a Node is proposed\n\n* `registration_approved`: A proposed Registration is approved\n\n* `registration_cancelled`: A proposed Registration is cancelled\n---\n\n* `preprint_initiated`: A preprint is made from the node (deprecated log, preprints are no longer made from nodes)\n\n* `preprint_license_updated`: A license is added or updated to the preprint (deprecated log, preprint actions are no longer logged on the node)\n\n* `preprint_file_updated`: The primary file of a preprint is updated (deprecated log, this action is now logged on the preprint)","operationId":"logs_actions","responses":{"200":{"description":"OK"}},"summary":"Actions","tags":["Logs"]}},"/addons/":{"get":{"description":"A paginated list of addons configurable with the OSF\n\n#### Returns\n\nReturns a JSON object containing `data` and `links` keys.\n\nThe `data` key contains an array of up to 10 addons. Each resource in the array is a separate addon object.\n\nThe `links` key contains a dictionary of links that can be used for [pagination](#tag/Pagination).\n\nThis request should never return an error.","operationId":"addons_list","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"items":{"properties":{"attributes":{"description":"The properties of the addon entity.","properties":{"categories":{"description":"List of categories this addon belongs to.","items":{"enum":["documentation","storage","bibliography","other","security","citations"],"type":"string"},"readOnly":true,"type":"array"},"description":{"description":"The description of the service provider.","readOnly":true,"type":"string"},"name":{"description":"The name of the third-party service provider.","readOnly":true,"type":"string"},"url":{"description":"The URL to the third-party service provider.","readOnly":true,"type":"string"}},"readOnly":true,"title":"Attributes","type":"object"},"id":{"description":"The identifier of the addon entity.","readOnly":true,"type":"string"},"type":{"description":"The type identifier of the addon entity (`addons`).","readOnly":true,"type":"string"}},"title":"Addon","type":"object"},"type":"array"}},"application/json":{"examples":{"response":{"value":{"data":[{"attributes":{"categories":["storage"],"description":"Box is a file storage add-on. Connect your Box account to an OSF project to interact with files hosted on Box via the OSF.","name":"Box","url":"http://www.box.com"},"id":"box","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"Dataverse is an open source software application to share, cite, and archive data. Connect your Dataverse account to share your Dataverse datasets via the OSF.","name":"Dataverse","url":"https://dataverse.harvard.edu/"},"id":"dataverse","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"Dropbox is a file storage add-on. Connect your Dropbox account to an OSF project to interact with files hosted on Dropbox via the OSF.","name":"Dropbox","url":"http://www.dropbox.com"},"id":"dropbox","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"Figshare is an online digital repository. Connect your figshare account to share your figshare files along with other materials in your OSF project.","name":"figshare","url":"http://www.figshare.com"},"id":"figshare","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"GitHub is a web-based Git repository hosting service. Connect your GitHub repo to your OSF project to share your code alongside other materials in your OSF project.","name":"GitHub","url":"http://www.github.com"},"id":"github","links":{},"type":"addon"},{"attributes":{"categories":["citations"],"description":"Mendeley is a reference management tool. Connecting Mendeley folders to OSF projects allows you and others to view, copy, and download citations that are relevant to your project from the Project Overview page.","name":"Mendeley","url":"http://www.mendeley.com"},"id":"mendeley","links":{},"type":"addon"},{"attributes":{"categories":["citations"],"description":"Zotero is a reference management tool. Connecting Zotero folders to OSF projects allows you and others to view, copy, and download citations that are relevant to your project from the Project Overview page.","name":"Zotero","url":"http://www.zotero.org"},"id":"zotero","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"ownCloud is an open source, self-hosted file sync and share app platform. Connect your ownCloud account to an OSF project to interact with files hosted on ownCloud via the OSF.","name":"ownCloud","url":"https://owncloud.org/"},"id":"owncloud","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"Amazon S3 is a file storage add-on. Connect your S3 account to an OSF project to interact with files hosted on S3 via the OSF.","name":"Amazon S3","url":"https://aws.amazon.com/s3/"},"id":"s3","links":{},"type":"addon"},{"attributes":{"categories":["storage"],"description":"Google Drive is a file storage add-on. Connect your Google Drive account to an OSF project to interact with files hosted on Google Drive via the OSF.","name":"Google Drive","url":"https://drive.google.com"},"id":"googledrive","links":{},"type":"addon"}],"links":{"per_page":1000,"total":10}}}}}}}},"summary":"List all addons","tags":["Addons"],"x-response-schema":"Addon"}},"/citations/styles/":{"get":{"description":"A paginated list of all standard citation styles available for rendering citations.\n\n#### Returns\n\nReturns a JSON object containing `data` and `links` keys.\n\nThe `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.\n\nThe `links` key contains a dictionary of links that can be used for [pagination](#tag/Pagination).\n\nThis request should never return an error.\n\n#### Filtering\n\nYou 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.\n\nCitation styles may be filtered by their `id`, `title`, `short-title`, and `summary`.\n\nYou can learn more about advanced filtering features [here](#tag/Filtering).","operationId":"citations_styles_list","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"items":{"properties":{"attributes":{"description":"The properties of the citation style entity.","properties":{"date_parsed":{"description":"The time at which the citation style was first parsed, as an iso8601 formatted timestamp.","format":"date-time","readOnly":true,"type":"string"},"short_title":{"description":"The short name for the citation style.","readOnly":true,"type":"string"},"summary":{"description":"The summary of the citation style.","readOnly":true,"type":"string"},"title":{"description":"The official name of the citation style.","readOnly":true,"type":"string"}},"readOnly":true,"required":["date_parsed","title"],"title":"Attributes","type":"object"},"id":{"description":"The identifier of the citation style, e.g. APA.","readOnly":true,"type":"string"},"links":{"description":"URLs to alternative representations of the citation style entity.","readOnly":true,"title":"Links","type":"object"},"type":{"description":"The type identifier of the citation style entity (`citation-styles`).","readOnly":true,"type":"string"}},"required":["id","type","attributes"],"title":"Citation Style","type":"object"},"type":"array"}},"application/json":{"examples":{"response":{"value":{"data":[{"attributes":{"date_parsed":"2015-02-16T04:16:25.732000","short_title":"AMR","title":"Academy of Management Review"},"id":"academy-of-management-review","links":{},"type":"citation-styles"}],"links":{"last":"https://api.osf.io/v2/citations/styles/?page=115","meta":{"per_page":10,"total":1149},"next":"https://api.osf.io/v2/citations/styles/?page=2"}}}}}}}},"summary":"List all citation styles","tags":["Citations"],"x-response-schema":"Citation Style"}},"/citations/styles/{style_id}/":{"get":{"description":"Retrieves the details of a citation style.\n#### Returns\nReturns a JSON object with a `data` key containing the representation of the requested citation style, if the request is successful.\n\nIf the request is unsuccessful, an `errors` key containing information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.","operationId":"citations_styles_read","parameters":[{"description":"The unique identifier of the citation style.","in":"path","name":"style_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"properties":{"attributes":{"description":"The properties of the citation style entity.","properties":{"date_parsed":{"description":"The time at which the citation style was first parsed, as an iso8601 formatted timestamp.","format":"date-time","readOnly":true,"type":"string"},"short_title":{"description":"The short name for the citation style.","readOnly":true,"type":"string"},"summary":{"description":"The summary of the citation style.","readOnly":true,"type":"string"},"title":{"description":"The official name of the citation style.","readOnly":true,"type":"string"}},"readOnly":true,"required":["date_parsed","title"],"title":"Attributes","type":"object"},"id":{"description":"The identifier of the citation style, e.g. APA.","readOnly":true,"type":"string"},"links":{"description":"URLs to alternative representations of the citation style entity.","readOnly":true,"title":"Links","type":"object"},"type":{"description":"The type identifier of the citation style entity (`citation-styles`).","readOnly":true,"type":"string"}},"required":["id","type","attributes"],"title":"Citation Style","type":"object"}},"application/json":{"examples":{"response":{"value":{"data":{"attributes":{"date_parsed":"2015-02-16T04:16:26.233000","short_title":"APA","title":"American Psychological Association 6th edition"},"id":"apa","links":{},"type":"citation-styles"}}}}}}}},"summary":"Retrieve a citation style","tags":["Citations"],"x-response-schema":"Citation Style"}},"/comments/{comment_id}/":{"delete":{"description":"Deletes a comment. This action can be undone by setting deleted to False in a comment update request.\n\n#### Returns\n\nIf the request is successful, no content is returned.\n\nIf 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](#tag/Errors-and-Error-Codes) to understand why this request may have failed.","operationId":"comments_delete","parameters":[{"description":"The unique identifier of the comment you wish to delete.","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"}},"summary":"Delete a comment","tags":["Comments"]},"get":{"description":"Retrieves the details of a comment\n\n#### Returns\n\nReturns a JSON object with a `data` key containing the representation of the requested comment, if the request was successful.\n\nIf the request is unsuccessful, an `errors` key containing information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.","operationId":"comments_read","parameters":[{"description":"The unique identifier of the comment you wish to retrieve.","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"example":{"data":{"attributes":{"content":"comment content"},"relationships":{"target":{"data":{"id":"{target_id}","type":"{target_type}"}}},"type":"comments"}},"properties":{"attributes":{"description":"The properties of the comment entity.","properties":{"can_edit":{"description":"Whether or not the current user has permission to edit this comment","readOnly":true,"type":"boolean"},"content":{"description":"The content of the comment.","readOnly":false,"type":"string"},"date_created":{"description":"The time at which the comment was created, as an iso8601 formatted timestamp.","format":"date-time","readOnly":true,"type":"string"},"date_modified":{"description":"The time at which the comment was last modified, as an iso8601 formatted timestamp.","format":"date-time","readOnly":true,"type":"string"},"deleted":{"description":"Whether or not the comment is deleted.","readOnly":true,"type":"boolean"},"has_children":{"description":"Whether or not the comment has replies.","readOnly":true,"type":"boolean"},"has_report":{"description":"Whether or not the comment the current user reported this as spam.","readOnly":true,"type":"boolean"},"is_abuse":{"description":"Whether or not the comment is flagged or confirmed spam.","readOnly":true,"type":"boolean"},"is_ham":{"description":"Whether or not an admin checked the legitimacy of this comment.","readOnly":true,"type":"boolean"},"modified":{"description":"Whether or not the comment has been edited.","readOnly":true,"type":"boolean"},"page":{"description":"The page type the comment is on, e.g. `node`, `registration`, `wiki`, `files`.","readOnly":true,"type":"string"}},"readOnly":false,"title":"Attributes","type":"object"},"id":{"description":"The identifier of the comment entity.","readOnly":true,"type":"string"},"links":{"description":"URLs to alternative representations of the comment entity.","properties":{"self":{"description":"A link to the detail page for the comment.","format":"URL","readOnly":true,"type":"string"}},"readOnly":true,"title":"Links","type":"object"},"relationships":{"description":"URLs to other entities or entity collections that have a relationship to the comment entity.","properties":{"node":{"description":"A relationship to the node the comment is on.","format":"URL","readOnly":true,"type":"string"},"replies":{"description":"A relationship to the replies to the comment.","format":"URL","readOnly":true,"type":"string"},"reports":{"description":"A relationship to the reports connected to the comment.","format":"URL","readOnly":true,"type":"string"},"target":{"description":"A relationship to the target of the comment.","format":"URL","readOnly":true,"type":"string"},"user":{"description":"A relationship to the user who created the comment.","format":"URL","readOnly":true,"type":"string"}},"readOnly":false,"title":"Relationships","type":"object"},"type":{"description":"The type identifier of the comment entity (`comments`).","readOnly":true,"type":"string"}},"required":["id"],"title":"Comment","type":"object"}},"application/json":{"examples":{"response":{"value":{"data":{"attributes":{"can_edit":true,"content":"comments about things","date_created":"2017-02-10T20:44:03.185000","date_modified":"2017-02-10T20:44:03.193000","deleted":false,"has_children":false,"has_report":false,"is_abuse":false,"is_ham":false,"modified":false,"page":"node"},"id":"twpgrpv78d8s","links":{"self":"https://api.osf.io/v2/comments/twpgrpv78d8s/"},"relationships":{"node":{"links":{"related":{"href":"https://api.osf.io/v2/nodes/gvuew/","meta":{}}}},"replies":{"links":{"related":{"href":"https://api.osf.io/v2/nodes/gvuew/comments/?filter%5Btarget%5D=twpgrpv78d8s","meta":{}}}},"reports":{"links":{"related":{"href":"https://api.osf.io/v2/comments/twpgrpv78d8s/reports/","meta":{}}}},"target":{"links":{"related":{"href":"https://api.osf.io/v2/nodes/gvuew/","meta":{"type":"nodes"}}}},"user":{"links":{"related":{"href":"https://api.osf.io/v2/users/rnizy/","meta":{}}}}},"type":"comments"}}}}}}}},"summary":"Retrieve a comment","tags":["Comments"],"x-response-schema":"Comment"},"put":{"description":"Updates the specified comment by setting the values of the parameters passed. Any parameters not provided will be left unchanged.\n#### Returns\nReturns JSON with a `data` key containing the new representation of the updated comment, if the request is successful.\n\nIf the request is unsuccessful, JSON with an `errors` key containing information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.","operationId":"comments_put","parameters":[{"description":"The unique identifier of the comment you wish to update.","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"example":{"data":{"attributes":{"content":"changed comment content"},"id":"{comment_id}","type":"comments"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"OK"}},"summary":"Update a comment","tags":["Comments"]}},"/files/{file_id}/":{"get":{"description":"Retrieves the details of a file (or folder)\n\n#### Returns\n\nReturns 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.\n\nIf the request is unsuccessful, an `errors` key containing info