(Mar 23, 2026 10:34 AM)7 Wrote:  Could we also get a MD or json link for AI training? Rather than scraping the page

(Mar 23, 2026 10:42 AM)Oh_Well Wrote:  Here you go!

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://hfapidocs.site/)

## 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://hfapidocs.site/)

## Base Details

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

## 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://hfapidocs.site/)
- After approval, you receive a `client_id` and `client_secret` used in the OAuth authorization code flow. [hfapidocs](https://hfapidocs.site/)
- OAuth steps: [hfapidocs](https://hfapidocs.site/)
  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://hfapidocs.site/)
- Rotate tokens if compromised and handle revocation and 401 responses gracefully. [hfapidocs](https://hfapidocs.site/)

## Scopes & Permissions

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

Main scopes (during beta):

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

Scope changes:

- Increasing permissions requires users to re‑authorize the application. [hfapidocs](https://hfapidocs.site/)

## Reading Data (`/read`)

General pattern:

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

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

- Fetch current user data plus a specific thread: [hfapidocs](https://hfapidocs.site/)
  - 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://hfapidocs.site/)
  - 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://hfapidocs.site/)

- `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://hfapidocs.site/)

## 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://hfapidocs.site/)
- Requires corresponding write scope for the resource (e.g., Posts, Bytes). [hfapidocs](https://hfapidocs.site/)
- Body uses an `asks` object with underscore‑prefixed input fields (e.g., `_tid`, `_message`, `_amount`, `_to_uid`). [hfapidocs](https://hfapidocs.site/)

Common write flows the agent can help describe:

- Reply to a thread: [hfapidocs](https://hfapidocs.site/)
  - Use `/write` or `/write/posts` with `asks.posts._tid` and `asks.posts._message`.  
- Create a thread: [hfapidocs](https://hfapidocs.site/)
  - Use `POST /write/threads` with appropriate inputs (e.g., forum id, subject, message) according to the `asks` schema.  
- Manage Bytes: [hfapidocs](https://hfapidocs.site/)
  - `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://hfapidocs.site/)

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

## 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://hfapidocs.site/)
- Rate limiting – responses may include `x-rate-limit-remaining` header that callers should monitor to avoid throttling. [hfapidocs](https://hfapidocs.site/)
- Validation errors – write requests may fail if required input fields or scopes are missing. [hfapidocs](https://hfapidocs.site/)
- Revocation – users can revoke app access from their Authorized Apps page; apps should detect invalid tokens and trigger re‑authorization. [hfapidocs](https://hfapidocs.site/)

## 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://hfapidocs.site/)
- Help choose minimal scopes for use cases like profile dashboards, post analysis, Bytes management tools, or contract trackers. [hfapidocs](https://hfapidocs.site/)
- Draft example HTTP requests (headers, JSON bodies) for `/read` and `/write` endpoints, including nested `asks` structures. [hfapidocs](https://hfapidocs.site/)
- Debug common integration issues (wrong endpoint, missing `_` inputs, scope mismatches, 401s, rate limiting). [hfapidocs](https://hfapidocs.site/)
- Suggest secure architecture patterns: backend‑only token storage, rotating secrets, handling revocation flows. [hfapidocs](https://hfapidocs.site/)
- Point users to community resources such as the PHP example by Xerotic and the Python integration by ENKI on GitHub. [hfapidocs](https://hfapidocs.site/)

## Limitations & Safety Notes

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

(Mar 23, 2026 10:23 AM)Omniscient Wrote:  Unbelievable. I have such bad luck sometimes.

I spoke with Oh_Well and got permission to host this on an HF subdomain. I'm thinking to use the Wiki server. It's just some static pages, no big deal.

Unfortunately, I didn't setup the Wiki server and it's all very basic and manual commands (no Control Panel). That's fine, I go to edit the confs for Nginx, seemingly goes well. I try to install a cert (Cerbot w/Letsencrypt) and I get an error. It's older Debian server so I go start an apt update. That doesn't go well. Now I'm locked out of the server, pretty sure if I restart it that it won't come up. Wiki online for now and I've done a DB backup and luckily I had a connection open with SFTP and I'm trying to DL a full site backup.

What a waste of my time. This will likely kill my entire Monday. I have to get this backup done the reinstall the OS and build the server from scratch again (with Control Panel this time) and setup both the wiki and the apidocs.

Insane.

(Mar 23, 2026 10:44 AM)7 Wrote:  Thanks mate! Appreciated.
I was thinking about making a markdown scraper for API's globally.

Considering the way tech is going. It's much easier than rescraping the api docs

(Mar 23, 2026 10:49 AM)Oh_Well Wrote:  That's bad luck, sorry for triggering that!!


Have you considered using moltbook to exhange docs/API info?

(Mar 24, 2026 07:08 AM)Oh_Well Wrote:  Omni got it working. So the HF API Documentation page is now under

apidocs.hackforums.net

Thank you Omniscient for taking the time to host this, and I hope the HF community uses it to its fullest potential!

(Mar 24, 2026 09:59 AM)Omniscient Wrote:  https://apidocs.hackforums.net/SKILLS.md

Added the SKILLS page.

btw, apparently it should be capitalized.

The swagger docs are going to be moved to Swagger.HackForums.net once xadamxk tells me the site url. I overwrote the apidocs cname and forgot to save the original url to do the swap. Oops.

(May 23, 2026 11:32 AM)xadamxk Wrote:  I'm trying to READ threads from a specific user in a specific subforum.

I have this, but the _fid isn't applying for some reason. Any idea why?
Also, how does pagination / sort order work? I can't find shit when it comes to pagination / offsets haha

For example:

Code

{
  "asks": {
    "threads": {
      "_fid": 2,
      "_uid": 1,
      "tid": true,
      "uid": true,
      "subject": true,
      "dateline": true,
      "fid": true
    }
  }
}

EDIT: Turns out the threads search parameters only support these and not fid :(

Code

'_uid' => [59852261], // ...or search by UID and optional _page/_perpage parameters
        '_page' => [123],
        '_perpage' => [123],

Here are the actual "docs" if anyone else needs them: https://hackforums.net/showthread.php?tid=6083782