Getting Started

The Hackaday Developer Platform enables applications to access data from Hackaday.io through two types of APIs:

  • Public APIs: Provide read-only access to publicly available information.
  • Private APIs: Offer access to user-specific data via OAuth 2.0, only when the user explicitly grants access using a special scope.

This documentation will guide you through the steps to authenticate, authorize, and interact with both API types effectively.

Overview

API Base URL

All requests should be made against: https://hackaday.io/v2

Response and Request Format

  • Format: JSON
  • Header Required: Content-Type: application/json

Authentication Methods

API Key Authentication (Public APIs)

Public APIs provide read-only access to Hackaday’s public data such as projects, users, tags, logs, and components.

  • API Key: Mandatory for all public endpoints
  • Limitations: API Key does not grant access to private user data

Header Format:

X-API-Key: YOUR_API_KEY

Example Request (cURL):

curl -X GET "https://hackaday.io/v2/projects" \
  -H "X-API-Key: YOUR_API_KEY"

Error Response (Missing Key):

{ "error": "api_key required" }

OAuth 2.0 Authentication (Private APIs)

Private APIs require OAuth 2.0 and explicit user authorization with the private-apis:read scope.

  • OAuth is required for all private endpoints.
  • If a user does not grant the private-apis:read scope, only public data will be accessible even after OAuth.
  • Private endpoints return 403 if the scope is not present.

Step 1: Redirect User for Authorization

GET https://hackaday.io/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&response_type=code
&scope=private-apis:read

Step 2: Exchange Authorization Code for Access Token

POST https://hackaday.io/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
code=AUTHORIZATION_CODE
grant_type=authorization_code
redirect_uri=YOUR_REDIRECT_URI

Response Example:

{
  "access_token": "user_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_here"
}

Step 3: Using the Access Token

Authorization: Bearer YOUR_ACCESS_TOKEN

About Scopes

OAuth Scopes

Only one scope is currently supported for private APIs:

Scope Description
private-apis:read Grants access to user’s private data

Without this scope, private APIs are not accessible, even if OAuth authorization is successful.

API Access Matrix

Scenario API Access Allowed
API Key Only Public Data only
OAuth (No Scope Granted) Public Data only
OAuth + private-apis:read Public + Private Data
No Authentication No access (401 or 403 error)

Private and Public Endpoints

Public Endpoints

Projects

  • GET /projects
  • GET /projects/:id
  • GET /projects/:id/logs
  • GET /projects/:id/components
  • GET /projects/:id/tags

Users

  • GET /users/:id

Private Endpoints

Users

  • GET /users/me

Projects

  • POST /projects/:id/comments
  • POST /projects/:id/skull
  • POST /projects/:id/follow

Pagination

Use query parameters to paginate results:

?page=1&limit=20
  • Default page: 1
  • Default limit: 20 (max: 100)

Error Handling and Security

Error Handling

Status Code Meaning Description
200OKSuccess
400Bad RequestInvalid or missing parameters
401UnauthorizedMissing/invalid API key or token
403ForbiddenScope not granted or access denied
404Not FoundResource does not exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

Security Guidelines

  • Use HTTPS for all API calls.
  • Keep API Keys and Client Secrets confidential.
  • Never expose tokens or secrets in frontend code.
  • Store and refresh OAuth tokens securely.

Interactive API Testing

Access the interactive API documentation at:

https://dev.hackaday.io → Click “API Docs”

  1. Click “Authorize”.
  2. Provide your API Key, or OAuth Client ID + Secret.
  3. Select private-apis:read if you want to test private APIs.
  4. Test endpoints live within the interface.

Support

Terms of Use

Violations may lead to revoked access.