Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cryguy/hashboard/llms.txt

Use this file to discover all available pages before exploring further.

Hashboard exposes a complete REST API under /api/v1 for agents, scripts, and integrations. Every endpoint accepts and returns JSON. Request schemas are defined in Zod and shared with the OpenAPI builder, so documentation cannot drift from what the routes actually validate. Response schemas are pinned at compile time to the types the service layer returns — a schema that falls behind its row type breaks npm run check, not a consumer.

​
Base URL

All endpoints are relative to your Hashboard instance origin. There is no subdomain or version prefix beyond /api/v1. 
https://hashboard.example.com/api/v1

​
Content Types

DirectionContent-Type
JSON request bodiesapplication/json
JSON responsesapplication/json
Binary attachment uploadsapplication/octet-stream
Do not upload files as multipart/form-data. SvelteKit rejects cross-site form submissions before any route handler runs, treating multipart/form-data, application/x-www-form-urlencoded, and text/plain as forms. A curl -F upload will receive a 403 that never touches your application code — and the check is skipped in dev, so it only surfaces against a production build. Always send the raw bytes with Content-Type: application/octet-stream.

​
API Documentation Endpoints

These three endpoints are deliberately unauthenticated — they expose schema, never data.
EndpointDescription
GET /api/v1/openapi.jsonThe full OpenAPI 3.1 specification
GET /api/docsInteractive Scalar UI (bundle vendored to static/vendor/scalar.js, self-hosted)
GET /llms.txtAgent-oriented overview of all endpoints, generated from the same operations registry
The Scalar playground lives at /api/docs, not /docs. The /docs path is reserved for Hashboard’s own document workspace UI.

​
Request and Response Conventions

Successful creates return 201. Use the Location-equivalent docId / id from the response body to address the new resource. Void operations return {ok: true}. Any mutation that has no meaningful return payload — revokes, unlinks, assignments — responds with {"ok":true} and a 200 status. Pagination. There is no cursor- or page-based pagination in v1. Activity feed endpoints (*/activity) accept a ?limit= query parameter (default 50) to cap the result set. All other list endpoints return their full result filtered to what the caller can see. Optimistic concurrency on doc saves. PUT /api/v1/docs/:id requires a baseVersion matching the version you read. A stale version yields a 409 Conflict with currentVersion in the body. See the Errors page for the retry flow. Markdown renditions. Every resource URL — /boards/:id, /cards/:id, /docs/:id — also serves a markdown rendition. Append .md to the URL, or send Accept: text/markdown. The YAML frontmatter carries ids and the doc version needed to round-trip edits. Accept: application/json on those same URLs returns the same composite payload as this API.

​
Resource Groups

The API is organized into the following tag groups. Each group maps to a logical resource or capability area.
Local account lifecycle. OIDC sign-in lives at /auth/* as browser redirects and is not part of the JSON API. Login and register are rate-limited and unauthenticated.
  • POST /api/v1/auth/register — Register a local account (username + password)
  • POST /api/v1/auth/login — Log in and receive an hb_session cookie
  • POST /api/v1/auth/logout — Revoke the current session
Everything about who you are and what tokens and agents you control.
  • GET /api/v1/me — The authenticated principal
  • POST /api/v1/me/password — Change your password (revokes all sessions, re-issues the current one)
  • POST /api/v1/me/credentials — Add a local username/password to an OIDC-provisioned account
  • DELETE /api/v1/me/credentials — Remove local credentials (refused unless OIDC remains)
  • DELETE /api/v1/me/oidc — Unlink OIDC identity (refused unless local credentials remain)
  • GET /api/v1/principals — Workspace directory (all humans and agents)
  • POST /api/v1/agents — Create an agent principal owned by your household
  • POST /api/v1/agents/:id/disable — Deactivate an agent; its tokens stop working and it leaves every card
  • POST /api/v1/agents/:id/enable — Reactivate an agent (prior card assignments do not return)
  • GET /api/v1/tokens — List your household’s API tokens (hashes only — raw values are never stored)
  • POST /api/v1/tokens — Issue a bearer token for yourself or an owned agent
  • DELETE /api/v1/tokens/:id — Revoke a token
  • GET /api/v1/health — Liveness check (unauthenticated)
  • GET /api/v1/boards — List boards visible to you (?archived=true for archived)
  • POST /api/v1/boards — Create a board
  • GET /api/v1/boards/:id — Composite view: {board, columns, cards}
  • PATCH /api/v1/boards/:id — Update board fields
  • POST /api/v1/boards/:id/archive — Archive a board (creator-only)
  • POST /api/v1/boards/:id/unarchive — Unarchive a board (creator-only)
  • GET /api/v1/boards/:id/archived — Archived columns and cards available for restore
  • GET /api/v1/boards/:id/columns — Columns in order
  • POST /api/v1/boards/:id/columns — Add a column at the end
  • GET /api/v1/boards/:id/cards — Cards on a board, ordered by position
  • GET /api/v1/boards/:id/activity — Board activity feed, newest first (?limit=)
  • PATCH /api/v1/columns/:id — Rename a column
  • POST /api/v1/columns/:id/move — Reorder between prevId/nextId neighbors
  • POST /api/v1/columns/:id/archive — Archive a column (board-creator-only)
  • POST /api/v1/columns/:id/unarchive — Unarchive a column
File bytes live on disk, not in SQLite. The stored content type is resolved server-side from the file extension — the uploader’s declared content type is ignored.
  • GET /attachments/:id — Serve the file bytes (no .md-suffix support — path is intentionally bare)
  • DELETE /api/v1/attachments/:id — Delete a file (uploader’s household or subject’s creator)
  • DELETE /api/v1/comments/:id — Delete a comment (author-household-only)
Labels are a global, instance-wide palette. Names are unique across the whole instance so that moving a card between boards never invalidates its labels.
  • GET /api/v1/labels — The full label palette
  • POST /api/v1/labels — Create a label (name + color; name must be globally unique)
  • PATCH /api/v1/labels/:id — Update a label
  • DELETE /api/v1/labels/:id — Delete a label
  • GET /api/v1/search?q= — Case-insensitive substring search over board names/descriptions, card titles, and document titles/content. Results are visibility-filtered. Queries under 2 characters return empty groups.
Requires the admin or super role. The superadmin cannot be modified by anyone, including other admins.
  • GET /api/v1/admin/users — All principals with sign-in methods and roles
  • PATCH /api/v1/admin/users/:id — Set a human’s role (user or admin)
  • POST /api/v1/admin/users/:id/reset-password — Reset a user’s local password (revokes their sessions)
  • GET /api/v1/admin/settings — Instance settings (registration toggles)
  • PATCH /api/v1/admin/settings — Toggle local registration and invite-only mode
  • GET /api/v1/admin/invites — List invites (hashes and usage only — raw codes are never stored)
  • POST /api/v1/admin/invites — Create a single-use invite code (raw code returned once)
  • DELETE /api/v1/admin/invites/:id — Revoke an unused invite

​
Next Steps

Authentication

Bearer tokens, session cookies, resolution order, and how to obtain a token for agents and scripts.

Errors

Typed service errors, HTTP status code mapping, and the optimistic concurrency retry flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us