Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/osf:osf-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: OSF APIv2 Documentation Files API
description: This is the official documentation for the OSF (Open Science Framework) API v2.
version: '2.0'
termsOfService: https://osf.io/terms_of_use/
contact:
name: OSF Support Team
email: support@osf.io
url: https://help.osf.io/
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
x-logo:
url: https://cdn.cos.io/media/images/cos_center_logo_small.original.png
backgroundColor: transparent
servers:
- url: https://api.test.osf.io/v2
tags:
- name: Files
paths:
/files/{file_id}/:
get:
summary: Retrieve a file
description: 'Retrieves the details of a file (or folder)
#### Returns
Returns a JSON object with a `data` key containing the representation of the requested file, if the request was successful.'
parameters:
- in: path
required: true
name: file_id
description: The unique identifier of the file you wish to retrieve.
schema:
type: string
tags:
- Files
operationId: files_detail
x-response-schema: File
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
title: File
properties:
id:
type: string
readOnly: true
description: The identifier of the file entity.
type:
type: string
readOnly: true
description: The type identifier of the file entity (`files`).
attributes:
type: object
title: Attributes
readOnly: false
description: The properties of the file entity.
properties:
extra:
type: object
readOnly: true
description: Extra information, contains `hashes` (`sha256`, `md5`) and `downloads` count.
kind:
type: string
readOnly: true
description: The kind of files object it is (`file` or `folder`).
name:
type: string
readOnly: false
description: Name of the file
last_touched:
type: string
format: date-time
readOnly: true
description: 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:
type: string
readOnly: true
description: Unix-style path to the file relative to the provider root.
date_modified:
type: string
format: date-time
readOnly: true
description: The time at which the file was last modified, as an iso8601 formatted timestamp.
current_version:
type: integer
readOnly: true
description: Version number of the file.
delete_allowed:
type: boolean
readOnly: true
description: Whether or not deletion of the file is allowed.
date_created:
type: string
format: date-time
readOnly: true
description: The time at which the file was created, as an iso8601 formatted timestamp.
provider:
type: string
readOnly: true
description: The id of the file provider (e.g., `osfstorage`)
path:
type: string
readOnly: true
description: The unique identifier for this file entity for this project and storage provider.
current_user_can_comment:
type: boolean
readOnly: true
description: Whether or not the current user is allowed to post comments.
guid:
type: string
readOnly: true
description: Global unique identifier (GUID) for this file (if one has been assigned).
checkout:
type: string
readOnly: true
description: SOON TO BE DEPRECATED, see relationships checkout.
tags:
type: array
items:
type: string
readOnly: true
description: A list of strings that describe this file, as entered by project contributors.
size:
type: integer
readOnly: true
description: Size of the file in bytes.
relationships:
type: object
title: Relationships
readOnly: true
description: Links to other entities or entity collections that have a relationship to the file entity.
properties:
node:
type: string
format: URL
readOnly: true
description: A link to the node the file is on.
checkout:
type: string
format: URL
readOnly: true
description: A link to the user who checked out the file.
comments:
type: string
format: URL
readOnly: true
description: A link to the comments on the file.
versions:
type: string
format: URL
readOnly: true
description: A link to the versions of the file.
links:
type: object
title: Links
readOnly: true
description: Links to alternative representations of the file entity.
properties:
info:
type: string
format: URL
readOnly: true
description: A link to the page to view a file's information or a folder's contents.
self:
type: string
format: URL
readOnly: true
description: A link to the detail page for the file.
move:
type: string
format: URL
readOnly: true
description: The Waterbutler API route for file moves.
new_folder:
type: string
format: URL
readOnly: true
description: The Waterbutler API route for creating a new subfolder (does not exist for files).
upload:
type: string
format: URL
readOnly: true
description: The Waterbutler API route for file uploads.
download:
type: string
format: URL
readOnly: true
description: The Waterbutler API route for file downloads.
delete:
type: string
format: URL
readOnly: true
description: The Waterbutler API route for file deletions.
example:
data:
relationships:
node:
links:
related:
href: https://api.osf.io/v2/nodes/ezcuj/
meta: {}
comments:
links:
related:
href: https://api.osf.io/v2/nodes/ezcuj/comments/?filter%5Btarget%5D=sejcv
meta: {}
versions:
links:
related:
href: https://api.osf.io/v2/files/553e69248c5e4a219919ea54/versions/
meta: {}
links:
info: https://api.osf.io/v2/files/553e69248c5e4a219919ea54/
self: https://api.osf.io/v2/files/553e69248c5e4a219919ea54/
move: https://files.osf.io/v1/resources/ezcuj/providers/osfstorage/553e69248c5e4a219919ea54
upload: https://files.osf.io/v1/resources/ezcuj/providers/osfstorage/553e69248c5e4a219919ea54
download: https://files.osf.io/v1/resources/ezcuj/providers/osfstorage/553e69248c5e4a219919ea54
delete: https://files.osf.io/v1/resources/ezcuj/providers/osfstorage/553e69248c5e4a219919ea54
attributes:
extra:
hashes:
sha256: 2450eb9ff3db92a1bff370368b0552b270bd4b5ca0745b773c37d2662f94df8e
md5: 44325d4f13b09f3769ede09d7c20a82c
downloads: 442
kind: file
name: OSC2012.pdf
last_touched: '2015-09-18T01:11:16.328000'
materialized_path: /OSC2012.pdf
date_modified: '2014-10-17T19:24:12.264Z'
current_version: 1
delete_allowed: true
date_created: '2014-10-17T19:24:12.264Z'
provider: osfstorage
path: /553e69248c5e4a219919ea54
current_user_can_comment: true
guid: sejcv
checkout: null
tags: []
size: 216945
type: files
id: 553e69248c5e4a219919ea54
patch:
summary: Update a file
description: '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.'
parameters:
- in: path
required: true
name: file_id
description: The unique identifier of the file you wish to update.
schema:
type: string
tags:
- Files
operationId: files_patch
responses:
'200':
description: OK
requestBody:
content:
application/json:
schema:
type: object
example:
data:
type: files
id: '{file_id}'
attributes:
name: new file name.jpg
required: true
/files/{file_id}/versions/:
get:
summary: List all file versions
description: '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.'
parameters:
- in: path
required: true
name: file_id
description: The unique identifier of the file from which you want to retrieve versions.
schema:
type: string
tags:
- Files
operationId: files_versions
x-response-schema: File Version
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
title: File Version
properties:
id:
type: string
readOnly: true
description: The identifier of the file version.
type:
type: string
readOnly: true
description: The type identifier of the file versions entity (`file_versions`).
attributes:
type: object
readOnly: true
description: The properties of the file versions entity.
properties:
content_type:
type: object
readOnly: true
description: MIME content-type for the file (null if unavailable).
date_created:
type: string
format: date-time
readOnly: true
description: The date of the file version creation, as an iso8601 formatted timestamp.
size:
type: integer
readOnly: true
description: Size of the file in bytes.
links:
type: object
readOnly: true
description: Links to alternative representations of the file version entity.
properties:
self:
type: string
format: URL
readOnly: true
description: A link to the detail page for a file version.
html:
type: string
format: URL
readOnly: true
description: A link to the html version page.
example:
data:
- links:
self: https://api.osf.io/v2/files/553e69248c5e4a219919ea54/versions/1/
html: https://osf.io/ezcuj/files/osfstorage/553e69248c5e4a219919ea54?revision=1
attributes:
content_type: application/octet-stream
date_created: '2017-01-01T12:34:56.78910'
size: 216945
type: file_versions
id: '1'
links:
first: null
last: null
prev: null
next: null
meta:
total: 1
per_page: 10
/files/{file_id}/versions/{version_id}/:
get:
summary: Retrieve a file version
description: '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.'
parameters:
- in: path
required: true
name: file_id
description: The unique identifier of the file from which you want to retrieve versions.
schema:
type: string
- in: path
required: true
name: version_id
description: The file version number you want to retrieve.
schema:
type: string
tags:
- Files
operationId: files_version_detail
x-response-schema: File Version
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
title: File Version
properties:
id:
type: string
readOnly: true
description: The identifier of the file version.
type:
type: string
readOnly: true
description: The type identifier of the file versions entity (`file_versions`).
attributes:
type: object
readOnly: true
description: The properties of the file versions entity.
properties:
content_type:
type: object
readOnly: true
description: MIME content-type for the file (null if unavailable).
date_created:
type: string
format: date-time
readOnly: true
description: The date of the file version creation, as an iso8601 formatted timestamp.
size:
type: integer
readOnly: true
description: Size of the file in bytes.
links:
type: object
readOnly: true
description: Links to alternative representations of the file version entity.
properties:
self:
type: string
format: URL
readOnly: true
description: A link to the detail page for a file version.
html:
type: string
format: URL
readOnly: true
description: A link to the html version page.
example:
data:
links:
self: https://api.osf.io/v2/files/553e69248c5e4a219919ea54/versions/1/
html: https://osf.io/ezcuj/files/osfstorage/553e69248c5e4a219919ea54?revision=1
attributes:
content_type: application/octet-stream
date_created: '2017-01-01T12:34:56.78910'
size: 216945
type: file_versions
id: '1'
/preprints/{preprint_id}/files/:
get:
summary: List storage providers for a preprint
description: 'Retrieve a list of storage providers for the specified preprint. Only "osfstorage" is supported for preprints.
#### Permissions
- Public storage providers are accessible to unauthenticated users.
- Viewing non-public preprints requires appropriate permissions.'
tags:
- Files
operationId: preprint_storage_providers_list
parameters:
- name: preprint_id
in: path
required: true
description: The unique identifier of the preprint.
schema:
type: string
responses:
'200':
description: Successful retrieval of storage providers.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
required:
- id
- type
- attributes
- links
properties:
id:
type: string
description: The name of the storage provider.
example: osfstorage
type:
type: string
example: storage-providers
attributes:
type: object
properties:
name:
type: string
description: The name of the storage provider.
example: osfstorage
default:
type: boolean
description: Whether this provider is the default.
example: true
links:
type: object
properties:
upload:
type: string
description: Upload URL for this storage provider.
files:
type: string
description: Link to files within this storage provider.
example:
data:
- id: osfstorage
type: storage-providers
attributes:
name: osfstorage
default: true
links:
upload: https://files.osf.io/v1/resources/abc12/providers/osfstorage/
files: https://api.osf.io/v2/preprints/abc12/files/osfstorage/
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. You do not have permission to view storage providers for this preprint.
'404':
description: Not Found. No preprint matches the given ID.
/preprints/{preprint_id}/files/osfstorage/:
get:
summary: List files for a preprint in osfstorage
description: 'Retrieve a list of files stored in the `osfstorage` provider for the specified preprint. Only "osfstorage" is available for preprints.
#### Permissions
- Public files are accessible to unauthenticated users.
- Viewing non-public files requires appropriate permissions.'
tags:
- Files
operationId: preprint_files_list
parameters:
- name: preprint_id
in: path
required: true
description: The unique identifier of the preprint.
schema:
type: string
responses:
'200':
description: Successful retrieval of files in osfstorage.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
required:
- id
- type
- attributes
- links
properties:
id:
type: string
description: The ID of the file.
example: 5b8df35e8c7d2e001d6fa3f9
type:
type: string
example: files
attributes:
type: object
properties:
name:
type: string
description: The name of the file.
example: paper.pdf
kind:
type: string
description: Type of the file object ('file' or 'folder').
example: file
size:
type: integer
description: Size of the file in bytes.
example: 102400
modified:
type: string
format: date-time
description: Last modified date of the file.
example: '2023-09-01T12:00:00Z'
contentType:
type: string
description: MIME type of the file.
example: application/pdf
links:
type: object
properties:
download:
type: string
description: URL to download the file.
upload:
type: string
description: URL to upload new versions of the file.
example:
data:
- id: 5b8df35e8c7d2e001d6fa3f9
type: files
attributes:
name: paper.pdf
kind: file
size: 102400
modified: '2023-09-01T12:00:00Z'
contentType: application/pdf
links:
download: https://files.osf.io/v1/resources/abc12/providers/osfstorage/5b8df35e8c7d2e001d6fa3f9
upload: https://files.osf.io/v1/resources/abc12/providers/osfstorage/5b8df35e8c7d2e001d6fa3f9
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. You do not have permission to view these files.
'404':
description: Not Found. No preprint matches the given ID.
x-tagGroups:
- name: Welcome
tags:
- Introduction
- General Usage
- Authentication
- Pagination
- Versioning
- Filtering
- Sparse Fieldsets
- Embedding
- Request Formatting
- Errors & Error Codes
- Entities & Entity Collections
- name: API Reference
tags:
- Actions
- Addons
- Applications
- Base
- CEDAR Metadata
- Citations
- Comments
- Collections
- Collection Submissions
- Collection Submissions Actions
- Collection Providers
- Custom Metadata
- Files
- Licenses
- Logs
- Institutions
- Identifiers
- Registration Schemas
- Registration Schema Blocks
- Schema Responses
- Schema Response Actions
- Nodes
- Notification Subscriptions
- Preprints
- Preprint Providers
- Draft Registrations
- Registrations
- Registration Providers
- Regions
- OAuth Scopes
- Taxonomies
- Tokens
- Users
- View Only Links
- Wikis
- Subjects
- GUIDs
- Requests
- Resources