Developer Guide: API v2

Overview

HF API v2 is a major overhaul that adds OAuth-based authorization, granular scopes/permissions, write access, and a flexible request model using an asks payload to shape responses. Members can authorize your app and revoke access at any time from the Authorized Apps page.

• ✓Secure OAuth authorization code flow.
• ✓Granular scopes for data access.
• ✓Unified /read and /write model with nested resources.
• ✓Endpoint helpers (e.g., /read/posts) for common tasks.

Swagger

A Swagger version for trying the APIs is available at https://apidocs.hackforums.net/.

Scopes & Permissions

Choose the minimum scopes needed. During Beta the main scopes are:

If you later increase permissions, users must re-authorize.

Create a Developer App

Apply for a new app in the Developer Portal. Visit the Developer Portal. Upon approval you'll receive a Client ID and Secret Key used in the OAuth flow.

Application fields

• •
  Name: Shown to members when authorizing.
• •
  Description: What your app does and for whom.
• •
  Redirect URI: HTTPS URL you control to receive the OAuth code.
• •
  Details: Notes to admins about your intended use.
• •
  Permissions: Select the scopes you need.

Vendors are auto-approved; other applications are reviewed. You will be notified via PM when approved or denied.

OAuth Authorization Code Flow

1. 1
   Redirect the user to the HF OAuth authorize page with your client_id, response_type=code, and an optional state value.
2. 2
   HF prompts the user to grant your requested scopes. On success, HF redirects the user back to your Redirect URI with ?code=... and &state=... (if provided).
3. 3
   Exchange the code for an access token by POSTing to https://hackforums.net/api/v2/authorize with your client_id and client_secret.
4. 4
   Store the returned access_token securely and attach it as Authorization: Bearer <token> when calling the API.

Example: code → access token

curl -X POST \
  'https://hackforums.net/api/v2/authorize' \
  -H 'accept: application/json' \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_SECRET_KEY' \
  --data-urlencode 'code=AUTHORIZATION_CODE'

The response includes access_token and may include the authorized uid.

Reading Data

Send a request to POST https://hackforums.net/api/v2/readwith an asks object describing the resources and fields you want. Attach Authorization: Bearer <token>.

Inputs to a resource are prefixed with _ (for example,_pid or _tid). Values marked true are returned.

Example: me + threads

POST https://hackforums.net/api/v2/read
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "asks": {
    "me": {
      "uid": true,
      "username": true,
      "usergroup": true
    },
    "threads": {
      "_tid": 6077763,
      "tid": true,
      "subject": true,
      "dateline": true,
      "firstpost": {
        "pid": true,
        "message": true,
        "author": {
          "uid": true,
          "username": true
        }
      }
    }
  }
}

Example: posts by pid

POST https://hackforums.net/api/v2/read/posts
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "asks": {
    "posts": {
      "_pid": [59852445],
      "pid": true,
      "tid": true,
      "uid": true,
      "fid": true,
      "dateline": true,
      "message": true,
      "subject": true,
      "edituid": true,
      "edittime": true,
      "editreason": true
    }
  }
}

Writing Data

Send a request to POST https://hackforums.net/api/v2/writewith an asks object describing the write action. Requires the corresponding write scope for the resource.

Example: reply to a thread

POST https://hackforums.net/api/v2/write
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "asks": {
    "posts": {
      "_tid": 6082555,
      "_message": "This is a test reply from the API."
    }
  }
}

Example: Bytes actions

POST https://hackforums.net/api/v2/write/bytes
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "asks": {
    "bytes": {
      "_to_uid": 123456,
      "_amount": 100
    }
  }
}

Other Bytes helpers: /write/bytes/deposit, /write/bytes/withdraw,/write/bytes/bump.

Endpoint Reference

Base URL: https://hackforums.net/api/v2

Errors & Rate Limits

• •
  401 Unauthorized: Missing or invalid access token. Ensure the Authorization: Bearer header is present and valid.
• •
  Rate Limiting: Responses may include x-rate-limit-remaining.
• •
  Validation: Write requests require the appropriate scope and input fields (e.g., _tid, _message).

Revocation

Members can revoke your app's access at any time from their Authorized Apps page. Your app should handle token invalidation gracefully and prompt users to re-authorize when needed.

Resources

FAQ