[Oh_Well]

HF API(v2) Documentation

This is my 500th post and 30th thread for October.
The perfect timing to get my Pumpkin award while giving back to the community!

Last week, I started working on a project that relies on the Hack Forums API.

As a developer who's used to clean and structured documentation, I found it a bit challenging to navigate the
threads discussing HF API v2.

So, I built a proper documentation page.

It covers everything needed to get started with developer apps, including the OAuth flow, permission scopes, and practical examples for both reading and writing data using JSON-based asks objects.

> apidocs.hackforums.net <

Skills.md
Spoiler (Click to View)

Code

HF API v2 Skills
=================

This file describes how an AI agent can understand and work with the **Hack Forums API v2** to help users design, debug, or reason about integrations. [hfapidocs](https://apidocs.hackforums.net/)

## Core Concept

- HF API v2 is an OAuth-based HTTP API that exposes read and write operations for Hack Forums resources (users, posts, threads, bytes, contracts, etc.) via a unified `/read` and `/write` model plus helper endpoints. [hfapidocs](https://apidocs.hackforums.net/)

## Base Details

- Base URL: `https://hackforums.net/api/v2`. [hfapidocs](https://apidocs.hackforums.net/)
- Main methods: `POST` with JSON bodies using an `asks` object to describe requested resources and fields. [hfapidocs](https://apidocs.hackforums.net/)
- Authentication: `Authorization: Bearer ACCESS_TOKEN` header with OAuth 2.0 access tokens. [hfapidocs](https://apidocs.hackforums.net/)

## OAuth & App Setup

The agent should know how to describe and reason about the OAuth flow, but not execute it itself.

- Developer apps are created in the HF Developer Portal (`usercp.php?action=apideveloper`) where you define name, description, redirect URI, details, and requested permissions (scopes). [hfapidocs](https://apidocs.hackforums.net/)
- After approval, you receive a `client_id` and `client_secret` used in the OAuth authorization code flow. [hfapidocs](https://apidocs.hackforums.net/)
- OAuth steps: [hfapidocs](https://apidocs.hackforums.net/)
  1. Redirect user to HF authorize page with `client_id`, `response_type=code`, optional `state`.  
  2. User grants scopes; HF redirects back to your redirect URI with `code` and `state` (if supplied).  
  3. Exchange `code` for an access token via `POST https://hackforums.net/api/v2/authorize` using form-encoded body (`grant_type=authorization_code`, `client_id`, `client_secret`, `code`).  
  4. Store the `access_token` securely and send it as a Bearer token on API calls.

Security constraints the agent should remind users of:

- Never put `client_secret` or access tokens in front-end or public code. [hfapidocs](https://apidocs.hackforums.net/)
- Rotate tokens if compromised and handle revocation and 401 responses gracefully. [hfapidocs](https://apidocs.hackforums.net/)

## Scopes & Permissions

The agent should help users choose minimal scopes and understand what each scope unlocks. [hfapidocs](https://apidocs.hackforums.net/)

Main scopes (during beta):

- Basic Info – public profile of the authorized user (e.g., `uid`, `username`, `usergroup`). [hfapidocs](https://apidocs.hackforums.net/)
- Advanced Info – private profile details of the authorized user (e.g., `unreadpms`, `invisible`, `totalpms`). [hfapidocs](https://apidocs.hackforums.net/)
- Posts – access to forums, threads, posts; includes optional write permissions. [hfapidocs](https://apidocs.hackforums.net/)
- Users – read public info of other members (`uid`, `username`, `avatar`, etc.). [hfapidocs](https://apidocs.hackforums.net/)
- Bytes – read Byte logs plus optional write actions (transfers, deposits, withdrawals, bumps). [hfapidocs](https://apidocs.hackforums.net/)
- Contracts – access contracts, disputes, and b-ratings. [hfapidocs](https://apidocs.hackforums.net/)

Scope changes:

- Increasing permissions requires users to re-authorize the application. [hfapidocs](https://apidocs.hackforums.net/)

## Reading Data (`/read`)

General pattern:

- Endpoint: `POST /read` or resource-specific helpers like `/read/posts`, `/read/me`, etc. [hfapidocs](https://apidocs.hackforums.net/)
- Body structure uses an `asks` object; inputs to resources are prefixed with `_` (e.g., `_pid`, `_tid`). [hfapidocs](https://apidocs.hackforums.net/)
- Fields set to `true` are requested back in the response. [hfapidocs](https://apidocs.hackforums.net/)

Example patterns the agent should be able to describe or generate:

- Fetch current user data plus a specific thread: [hfapidocs](https://apidocs.hackforums.net/)
  - Use `/read` with `asks.me` for user fields (e.g., `uid`, `username`, `usergroup`) and `asks.threads` with `_tid` and nested fields like `firstpost.message` and author info.  
- Fetch posts by `pid`: [hfapidocs](https://apidocs.hackforums.net/)
  - Use `/read/posts` with `asks.posts._pid` as a list and booleans for desired post fields (e.g., `pid`, `message`, `subject`, `dateline`, etc.).

Key read endpoints the agent should recognize: [hfapidocs](https://apidocs.hackforums.net/)

- `POST /read` – generic nested reads.  
- `POST /read/me` – current authorized user profile.  
- `POST /read/users` – public info of other users.  
- `POST /read/forums` – forum data.  
- `POST /read/threads` – threads by `tid`.  
- `POST /read/posts` – posts by `pid`.  
- `POST /read/bytes` – Byte logs.  
- `POST /read/contracts` – contracts data.  
- `POST /read/disputes` – disputes data.  
- `POST /read/bratings` – b-ratings.  
- `POST /read/sigmarket/market` and `POST /read/sigmarket/order` – signature market resources. [hfapidocs](https://apidocs.hackforums.net/)

## Writing Data (`/write`)

General pattern:

- Endpoint: `POST /write` or resource-specific helpers such as `/write/posts`, `/write/bytes`, `/write/bytes/deposit`, `/write/bytes/withdraw`, `/write/bytes/bump`. [hfapidocs](https://apidocs.hackforums.net/)
- Requires corresponding write scope for the resource (e.g., Posts, Bytes). [hfapidocs](https://apidocs.hackforums.net/)
- Body uses an `asks` object with underscore-prefixed input fields (e.g., `_tid`, `_message`, `_amount`, `_to_uid`). [hfapidocs](https://apidocs.hackforums.net/)

Common write flows the agent can help describe:

- Reply to a thread: [hfapidocs](https://apidocs.hackforums.net/)
  - Use `/write` or `/write/posts` with `asks.posts._tid` and `asks.posts._message`.  
- Create a thread: [hfapidocs](https://apidocs.hackforums.net/)
  - Use `POST /write/threads` with appropriate inputs (e.g., forum id, subject, message) according to the `asks` schema.  
- Manage Bytes: [hfapidocs](https://apidocs.hackforums.net/)
  - `POST /write/bytes` to send Bytes (`_to_uid`, `_amount`).  
  - `POST /write/bytes/deposit` to deposit to vault (minimum 100).  
  - `POST /write/bytes/withdraw` to withdraw from vault (minimum 100).  
  - `POST /write/bytes/bump` to bump a thread via Stanley Byte Bump. [hfapidocs](https://apidocs.hackforums.net/)

The agent should remind users that writes must pass validation (correct inputs, scopes, etc.). [hfapidocs](https://apidocs.hackforums.net/)

## Errors, Limits, and Revocation

The agent should be able to reason about error handling and give best-practice advice.

- 401 Unauthorized – usually due to missing or invalid access token; ensure Bearer token is present and not expired or revoked. [hfapidocs](https://apidocs.hackforums.net/)
- Rate limiting – responses may include `x-rate-limit-remaining` header that callers should monitor to avoid throttling. [hfapidocs](https://apidocs.hackforums.net/)
- Validation errors – write requests may fail if required input fields or scopes are missing. [hfapidocs](https://apidocs.hackforums.net/)
- Revocation – users can revoke app access from their Authorized Apps page; apps should detect invalid tokens and trigger re-authorization. [hfapidocs](https://apidocs.hackforums.net/)

## Agent Capabilities & Use Cases

In conversations, the agent can:

- Explain how to register a **Hack Forums** developer app and which fields to fill out for specific use cases (e.g., bots, dashboards, trading tools). [hfapidocs](https://apidocs.hackforums.net/)
- Help choose minimal scopes for use cases like profile dashboards, post analysis, Bytes management tools, or contract trackers. [hfapidocs](https://apidocs.hackforums.net/)
- Draft example HTTP requests (headers, JSON bodies) for `/read` and `/write` endpoints, including nested `asks` structures. [hfapidocs](https://apidocs.hackforums.net/)
- Debug common integration issues (wrong endpoint, missing `_` inputs, scope mismatches, 401s, rate limiting). [hfapidocs](https://apidocs.hackforums.net/)
- Suggest secure architecture patterns: backend-only token storage, rotating secrets, handling revocation flows. [hfapidocs](https://apidocs.hackforums.net/)
- Point users to community resources such as the PHP example by Xerotic and the Python integration by ENKI on GitHub. [hfapidocs](https://apidocs.hackforums.net/)

## Limitations & Safety Notes

- The agent cannot obtain or manage real tokens or secrets; it only explains how to use them. [hfapidocs](https://apidocs.hackforums.net/)
- The agent should never suggest hard-coding `client_secret` or access tokens into public repos or client-side code. [hfapidocs](https://apidocs.hackforums.net/)
- The documentation referenced is unofficial; behavior may change and users should verify against the latest official materials if available. [hfapidocs](https://apidocs.hackforums.net/)

[Vectura]

Then we say, thank you Vectura for bringing to light how difficult the API is to understand; but despite that, thank you Vectura for still managing to put everything together to create a working Hackforums dash 😂

But really bud, HQ thread, thanks!

[Oh_Well]

Then we say, thank you Vectura for bringing to light how difficult the API is to understand; but despite that, thank you Vectura for still managing to put everything together to create a working Hackforums dash 😂

But really bud, HQ thread, thanks!

Thank you Vectura for bringing to light how difficult the API is to understand 🤣🤣

[Vectura]

Thank you Vectura for bringing to light how difficult the API is to understand 🤣🤣

Hahahahaha, no, that API is really hard to understand for a layman. The error handling built into it is really rubbish.

[genesai]

Excuse the ignorance for a second but what does HF API allow us to do? What do we need to integrated with HF for?
I mean this in no bad way, just genuine curiousity

[Vectura]

Thank you Vectura for bringing to light how difficult the API is to understand 🤣🤣

Hahahahaha, no, that API is really hard to understand for a layman. The error handling built into it is really rubbish.

[PhillyStyle]

I was thinking of making an program that lists the most recent threads/replies in selected forums. So that I don't have to click on each forum to see what is at the top of the list. Does that sound like something that could be done with the API?

Never mind, I don't have a Redirect URI.

[Oh_Well]

Excuse the ignorance for a second but what does HF API allow us to do? What do we need to integrated with HF for?
I mean this in no bad way, just genuine curiousity

You can do lot's of stuff!

Take a look at the dashboard Vectura created and you'll get a taste!

https://hackforums.net/showthread.php?tid=6310504

You can also run analytics, send automated reminders, lookup users, transfer bytes, manage contracts etc.

[CL1B]

Woah, this is quite nicely done! GG!

Omniscient what you think?

[Novo]

YOU ARE THE MAN Oh_Well!

[xadamxk]

Did you reference these docs at all?
https://github.com/xadamxk/hf-api-specification

I'd be curious to know if the API specs have changed since this was written.

[Terry A. Davis]

I appreciate immensely that Swagger docs were provided.

Since learning about it, and using it, I am a massive fan for documentation, not like I'll ever write an Agent for HF, but nice to see that it is documented in a nice way.

[Oh_Well]

Website is back online. It was down for a few feeks and I didn't realize it.

[Omniscient]

Doesn't everyone Vibe Code now the HF API? I would think something for a skills.md file would be better.

[CL1B]

Doesn't everyone Vibe Code now the HF API? I would think something for a skills.md file would be better.

Whether it's agentic or human coding, nicely written documentations go a long way.