Open Science Framework Getting Started: Setup & First API Call (2026)

Getting started overview

The Open Science Framework (OSF) provides a platform for managing research workflows, facilitating collaboration, and promoting open science practices. This guide focuses on the initial steps for new users, covering account creation, obtaining API credentials, and executing a basic API request. While OSF offers a web interface for most functions, its API enables programmatic interaction, allowing for automation and integration with other tools.

To effectively utilize OSF, users typically follow a sequence of steps:

1. Account Creation: Register for a free OSF account to gain access to the platform's features, including project creation and file storage.
2. API Key Generation: For programmatic access, generate a Personal Access Token (PAT) within your OSF account settings. This token authenticates your API requests.
3. First API Request: Use the generated PAT to make an initial API call, verifying connectivity and understanding the basic request structure.

The OSF API is designed for managing research projects, components, files, and user data programmatically. It adheres to the JSON:API specification, which defines how clients request and update resources, and how servers respond to those requests. Understanding this specification can aid in constructing more complex API interactions.

Quick Reference Steps

Create an account and get keys

Accessing the Open Science Framework, whether through its web interface or programmatically via its API, begins with creating an account. OSF accounts are free and provide access to features such as project creation, file storage, and collaboration tools. The free tier includes unlimited public projects and 5GB of private storage per project, making it suitable for individual researchers and small teams.

Account Creation

1. Navigate to the OSF signup page.
2. Enter your email address, full name, and create a password.
3. Review and accept the OSF Terms of Use and Privacy Policy.
4. Click "Sign Up".
5. Verify your email address by clicking the link in the confirmation email sent to you by OSF. This step is crucial for activating your account.

Once your account is active, you can log in and begin using the OSF web interface to create projects, upload files, and manage your research outputs.

Generating a Personal Access Token (PAT)

To interact with the OSF API programmatically, you need a Personal Access Token (PAT). A PAT acts as an authentication credential, allowing your applications or scripts to make requests on your behalf without requiring your password. It is essential to treat your PAT like a password and keep it secure.

1. Log in to your OSF account.
2. Navigate to your user settings by clicking your avatar in the top right corner and selecting "Settings".
3. In the settings menu, click on "Developer Apps & Integrations" or directly access the Personal Access Tokens page.
4. Click the "Create token" button.
5. Provide a descriptive name for your token (e.g., "My Research Script"). This helps you identify its purpose later.
6. Select the necessary scopes for your token. Scopes define the permissions your token will have. For a comprehensive interaction, you might select scopes like osf.full_read and osf.full_write. For an initial test, osf.full_read is sufficient to retrieve public project information.
7. Click "Create token".
8. Your PAT will be displayed once. Copy it immediately and store it securely. For security reasons, OSF will not display the token again after you navigate away from the page. If you lose it, you will need to revoke it and generate a new one.

The generated PAT will be used in the Authorization header of your API requests.

Your first request

With your OSF account created and a Personal Access Token (PAT) generated, you are ready to make your first API request. This initial request will demonstrate how to authenticate and retrieve data from the OSF API.

The OSF API is versioned (currently v2) and its base URL is https://api.osf.io/v2/. All API requests should be sent to this base URL, followed by the specific endpoint for the resource you wish to interact with.

Example: Fetching a Public Project

Let's retrieve information about a publicly available OSF project. You will need a Project ID (also known as a GUID) for a public project. You can find public project IDs by browsing OSF, or use a known public project for testing.

• Endpoint: /nodes/{node_id}/ (where {node_id} is the Project ID)
• Method: GET
• Authentication: Bearer Token in the Authorization header.

Using curl (Command Line)

Replace YOUR_PAT with your actual Personal Access Token and PROJECT_ID with a valid public OSF project ID (e.g., n8b3x for "Test Project for API").

curl -H "Authorization: Bearer YOUR_PAT" \
     https://api.osf.io/v2/nodes/PROJECT_ID/

A successful response will return a JSON object containing details about the specified project, similar to this (truncated for brevity):

{
  "data": {
    "id": "PROJECT_ID",
    "type": "nodes",
    "attributes": {
      "title": "Example Project Title",
      "description": "A description of the example project.",
      "date_created": "2023-01-01T12:00:00.000000Z",
      // ... other attributes ...
    },
    "relationships": {
      // ... relationships to other resources ...
    }
  }
}

Using Python with requests library

This example demonstrates how to make the same request using Python, a common choice for API interactions.

import requests
import os

# It's recommended to store your PAT securely, e.g., in an environment variable
PAT = os.environ.get("OSF_PAT")
PROJECT_ID = "PROJECT_ID"  # Replace with a valid public OSF project ID

if not PAT:
    print("Error: OSF_PAT environment variable not set.")
    exit()

headers = {
    "Authorization": f"Bearer {PAT}"
}

url = f"https://api.osf.io/v2/nodes/{PROJECT_ID}/"

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print("Successfully retrieved project data:")
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

Ensure you have the requests library installed (pip install requests) and replace PROJECT_ID with an actual public project ID. For example, the OSF API v2 documentation provides examples that often include specific project IDs for testing.

Common next steps

After successfully making your first API call, you can explore the broader capabilities of the Open Science Framework API. Common next steps often involve more complex data manipulation, integration with other tools, and deeper engagement with OSF's features.

Exploring the API Documentation

The OSF API v2 documentation is the primary resource for understanding all available endpoints, request parameters, and response structures. It provides detailed information on:

• Endpoints: Discover how to interact with projects (nodes), components, files, users, registrations, and more.
• Query Parameters: Learn how to filter, sort, and paginate results to retrieve specific datasets.
• Request Bodies: Understand the JSON structure required for creating or updating resources.
• Error Handling: Familiarize yourself with common error codes and their meanings.

Managing Projects and Files

One of the core uses of the OSF API is to manage research projects and their associated files programmatically:

• Create New Projects: Use the POST /v2/nodes/ endpoint to create new OSF projects or components.
• Upload and Download Files: Interact with the file storage endpoints to upload research data, code, or documents, and download existing files. This is particularly useful for automating data backups or integrating with computational workflows.
• Update Project Metadata: Modify project titles, descriptions, and other attributes using PATCH requests to the relevant node endpoints.

Integrating with Other Tools

The OSF API facilitates integration with various research tools and platforms. For instance, you could:

• Automate Data Synchronization: Develop scripts to automatically upload data from lab instruments or computational analyses to an OSF project.
• Connect with Electronic Lab Notebooks (ELNs): Integrate OSF with ELN systems to automatically archive experimental data or protocols.
• Build Custom Dashboards: Create personalized dashboards that pull project status, file counts, and contributor information directly from OSF.

Contributing to Open Science

OSF is a key platform for open science. Consider using the API to:

• Pre-register Studies: Programmatically create study registrations to increase transparency and reduce publication bias.
• Share Research Outputs: Automate the process of making research data, code, and materials publicly available on OSF.

Troubleshooting the first call

When making your first API call, you might encounter issues. Here are common problems and their solutions:

401 Unauthorized

This status code indicates that your request lacks valid authentication credentials. Common causes include:

• Missing or Incorrect PAT: Double-check that your Personal Access Token is correctly included in the Authorization: Bearer YOUR_PAT header and that there are no typos. Ensure you copied the full token when it was generated.
• Expired or Revoked PAT: If your token was created a long time ago, it might have expired or been manually revoked. Generate a new PAT from your OSF Developer Apps & Integrations settings.
• Incorrect Header Format: Ensure the header is precisely Authorization: Bearer YOUR_PAT, with "Bearer" followed by a space and then your token.

403 Forbidden

A 403 status code means your authentication was successful, but the authenticated user (via your PAT) does not have permission to access the requested resource or perform the requested action. This is often due to:

• Insufficient Token Scopes: The PAT you used might not have the necessary permissions (scopes) for the operation. For example, trying to modify a project with a read-only token will result in a 403. Go to your OSF Developer Apps & Integrations settings, review the scopes of your token, or create a new token with broader permissions (e.g., osf.full_read, osf.full_write).
• Private Project Access: Attempting to access a private project that your account does not have access to, or that the PAT's scopes do not permit.

404 Not Found

This indicates that the requested resource could not be found at the specified URL. Check for:

• Incorrect URL or Endpoint: Verify the API endpoint and base URL. Ensure there are no typos in https://api.osf.io/v2/ or the specific resource path (e.g., /nodes/PROJECT_ID/).
• Invalid Project/Node ID: The PROJECT_ID or node_id you are using might be incorrect or no longer exist. Double-check the ID from the OSF website.

Network or Connection Issues

If you receive no response or a connection error, consider:

• Internet Connectivity: Ensure your device has an active internet connection.
• Firewall/Proxy: Your network's firewall or proxy settings might be blocking outgoing requests to api.osf.io. Consult your network administrator if you suspect this is the case.
• DNS Resolution: Problems resolving api.osf.io to an IP address can cause connection failures.

Debugging Tools

• HTTP Client Logs: Most HTTP client libraries (like Python's requests) can log request and response details, including headers and body, which can be invaluable for debugging.
• Browser Developer Tools: If you're encountering issues with web-based interactions, browser developer tools (Network tab) can show the actual HTTP requests and responses being sent.
• OSF Help Documentation: The OSF Help Center contains articles and FAQs that might address specific issues.