HF API Documentation - Oh_Well - Oct 21, 2025
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.
Skills.md
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/)
![[Image: 2025-10-21-203845.png]](https://i.ibb.co/67jcknYN/2025-10-21-203845.png)
RE: HF API Documentation - Vectura - Oct 21, 2025
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!
RE: HF API Documentation - Oh_Well - Oct 21, 2025
(Oct 21, 2025 03:18 PM)Vectura Wrote: 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 🤣🤣
RE: HF API Documentation - Vectura - Oct 21, 2025
(Oct 21, 2025 03:20 PM)Oh_Well Wrote: 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.
RE: HF API Documentation - genesai - Oct 21, 2025
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
RE: HF API Documentation - Vectura - Oct 21, 2025
(Oct 21, 2025 03:20 PM)Oh_Well Wrote: 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.
RE: HF API Documentation - PhillyStyle - Oct 21, 2025
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.
RE: HF API Documentation - Oh_Well - Oct 21, 2025
(Oct 21, 2025 03:33 PM)genesai Wrote: 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.
RE: HF API Documentation - CL1B - Oct 23, 2025
Woah, this is quite nicely done! GG!
Omniscient what you think?
RE: HF API Documentation - Novo - Oct 23, 2025
YOU ARE THE MAN Oh_Well!
RE: HF API Documentation - xadamxk - Oct 26, 2025
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.
RE: HF API Documentation - Terry A. Davis - Nov 26, 2025
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.
RE: HF API Documentation - Oh_Well - Mar 10, 2026
Website is back online. It was down for a few feeks and I didn't realize it.
RE: HF API Documentation - Omniscient - Mar 22, 2026
Doesn't everyone Vibe Code now the HF API? I would think something for a skills.md file would be better.
RE: HF API Documentation - CL1B - Mar 23, 2026
(Mar 22, 2026 12:46 PM)Omniscient Wrote: 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.
|
![[Image: ZLazS1C.gif]](https://i.imgur.com/ZLazS1C.gif)