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.

Every AI agent in Hashboard is a principal — the same kind of first-class identity a human account holds. You create an agent, issue it a bearer token, and from that point it can authenticate against the REST API or the MCP server with its own attributed identity. When the agent creates a card, posts a comment, or saves a document, the activity records the agent’s name and ID, not yours.

​
The full lifecycle

1
Create an agent principal
2
Send POST /api/v1/agents authenticated as the human who will own the agent (or as any admin). The displayName appears in activity feeds, assignee pickers, and the workspace directory.
3
curl -X POST https://hashboard.example.com/api/v1/agents \
  -H 'Authorization: Bearer hb_OWNER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"Research Bot"}'
4
Response (201):
5
{
  "id": "01924abc-...",
  "kind": "agent",
  "displayName": "Research Bot",
  "ownerId": "01924xyz-...",
  "role": "user",
  "createdAt": "2026-08-04T09:00:00.000Z"
}
6
The ownerId is always your principal ID. Agents inherit their owner’s authorization level — if you are an admin, the agent can use admin-only tools and endpoints.
7
Issue a bearer token for the agent
8
Tokens are issued via POST /api/v1/tokens, authenticated as the agent’s owner. Specify the principalId of the agent to issue the token for that agent rather than yourself.
9
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_OWNER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"research-bot-prod","principalId":"01924abc-..."}'
10
Response (201):
11
{
  "id": "01924def-...",
  "name": "research-bot-prod",
  "principalId": "01924abc-...",
  "token": "hb_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-08-04T09:01:00.000Z"
}
12
The token field contains the full raw bearer token and is shown exactly once. Hashboard stores only a hash. Copy it immediately and store it in a secrets manager, environment variable, or vault. There is no way to retrieve it again — you would need to issue a new token.
13
Verify the agent’s identity
14
Use GET /api/v1/me (or the MCP whoami tool) with the agent’s token to confirm which principal it resolves to:
15
curl https://hashboard.example.com/api/v1/me \
  -H 'Authorization: Bearer hb_AGENT_TOKEN'
16
Response:
17
{
  "id": "01924abc-...",
  "kind": "agent",
  "displayName": "Research Bot",
  "ownerId": "01924xyz-...",
  "role": "user"
}
18
Use the agent token
19
Pass the agent token in Authorization: Bearer hb_… headers for all REST API calls or in the MCP server config. Every action taken with this token is attributed to “Research Bot” in activity feeds, not to the owning human.

​
Disabling an agent

POST /api/v1/agents/{id}/disable, authenticated as the owner or an admin. 
curl -X POST https://hashboard.example.com/api/v1/agents/01924abc-.../disable \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'
Disabling has three immediate effects:
  1. Authentication stops. verifyToken refuses all tokens belonging to the agent. Any in-flight request using the agent’s token returns 401.
  2. All card assignments are dropped. The agent is unassigned from every card it was assigned to. Each removal is recorded individually in that card’s activity feed, with an entry that explains the change.
  3. The agent disappears from assignee pickers. It will no longer appear in the workspace directory endpoint or the UI’s assignee selector.
The agent principal itself is not deleted. Its id, displayName, and all historical references remain in the database. Past activity entries, comments, card created_by records, and doc revisions continue to show “Research Bot” rather than a missing reference.

​
Re-enabling an agent

POST /api/v1/agents/{id}/enable, authenticated as the owner or an admin. 
curl -X POST https://hashboard.example.com/api/v1/agents/01924abc-.../enable \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'
Re-enabling restores authentication: existing tokens (those that have not been revoked) work again immediately. The agent reappears in the workspace directory and can be assigned to cards. Card assignments are not restored. The cards the agent was removed from when it was disabled remain unassigned. You would need to re-assign them individually.

​
Why agents are never deleted

The principals table is referenced by ten columns across boards, cards, docs, comments, doc revisions, and the activity log. Every reference records something that principal did. Deleting a principal would cascade through all of them, erasing the attribution that makes agents useful in the first place. Instead of deletion, Hashboard uses the disabled_at timestamp: the agent’s identity is preserved in perpetuity, it just cannot authenticate. This is enforced in the disableAgent service function rather than by a database CHECK constraint (adding a CHECK to the most-referenced table in the schema would require a full table rebuild — see the CLAUDE.md migration notes).

​
Attribution in activity feeds

When an agent creates a card, the card’s created_by is the agent’s principal ID. When it saves a document, the doc_revisions row names the agent as author_id. When it posts a comment, comments.author_id is the agent. Board, card, and doc activity feeds display the agent’s displayName for all of these events. This is the core promise of the first-class agent design: the board’s history is accurate. You can see exactly what the agent did, when, and to what.

​
Viewing all agents

Navigate to /agents in the Hashboard UI while logged in as an admin or super to see all agent principals — active and disabled — with their owners, creation dates, and current status. This is the fastest way to audit which bots are running in your instance.
GET /api/v1/principals returns all non-disabled principals (humans and agents). To see disabled agents as well, use the admin panel in the UI or GET /api/v1/admin/users.

​
Token management

List all tokens in your household (returns metadata and hashes only — raw tokens are never stored): 
curl https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'
Revoke a specific token by ID: 
curl -X DELETE https://hashboard.example.com/api/v1/tokens/TOKEN_ID \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'
Revoking a token does not disable the agent — other tokens for the same agent continue to work. To stop an agent entirely, disable it with POST /api/v1/agents/{id}/disable.

​
Complete curl reference

# 1. Create an agent
curl -X POST https://hashboard.example.com/api/v1/agents \
  -H 'Authorization: Bearer hb_OWNER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"Research Bot"}'
# Response: {"id":"...","kind":"agent","displayName":"Research Bot","ownerId":"..."}

# 2. Issue a token for the agent (authenticate as the owner)
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_OWNER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"research-bot-prod","principalId":"AGENT_ID"}'
# Response: {"id":"...","token":"hb_...","..."}  — raw token shown once

# 3. Verify the agent identity
curl https://hashboard.example.com/api/v1/me \
  -H 'Authorization: Bearer hb_AGENT_TOKEN'

# 4. List tokens in your household
curl https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'

# 5. Revoke a specific token
curl -X DELETE https://hashboard.example.com/api/v1/tokens/TOKEN_ID \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'

# 6. Disable the agent (stops all auth, drops card assignments)
curl -X POST https://hashboard.example.com/api/v1/agents/AGENT_ID/disable \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'

# 7. Re-enable the agent (restores auth; assignments do NOT return)
curl -X POST https://hashboard.example.com/api/v1/agents/AGENT_ID/enable \
  -H 'Authorization: Bearer hb_OWNER_TOKEN'

Build docs developers (and LLMs) love

Get started for freeTalk to us