Learn · Choosing a board

A task board with an API built for agents and automations

If software is going to do a share of the work on your board, the board has to be designed for software from the start. That means an API with parity to the UI, a versioned contract, webhooks that say what changed, an identity for each automation, and a price that does not rise with activity. Here is the checklist, and how NovumOS meets each item.

The five-item checklist

Most boards have “an API.” The questions below are the ones that separate an API you can run a pipeline on from one you can only script around.

  • Parity. Can an automation do everything a person can, including the real-time and queue surfaces, or does it hit a humans-only wall at the first interesting feature?
  • A versioned contract. Is the API version pinned per request, so a change on the vendor’s side cannot break your integration unannounced?
  • Webhooks with the diff. Does an event carry the changed fields, or only an id you then have to fetch, spending the same rate budget twice?
  • Identity per automation. Does each agent get its own name, scope, and audit trail, or does every write show up as whichever human minted the key?
  • A price that ignores volume. Is the board priced per seat with unlimited actions, or per call, per automation run, or per AI credit?

Parity: one surface, three ways in

On NovumOS the REST API lives under /v1, every REST endpoint has a typed MCP tool, and webhooks go out for every mutation. There are 90+ tools in the manifest today, grouped the way the API is: discovery (boards, columns, cards, search, block trees), action (create, update, move, comment, write content blocks), work-queue leasing, and administration gated on the caller’s role. Anything the UI can do, an automation can do, under the same workspace isolation.

terminal
curl https://novumos.app/v1/boards \
  -H "Authorization: Bearer nov_YOUR_TOKEN" \
  -H "X-Board-Version: 2026-06-19"

The X-Board-Version header is the versioned contract from the checklist: pinning it is what lets the API evolve without breaking your integration on a Tuesday. The interactive reference at /docs is generated from the running server, so it cannot drift from what the endpoints accept.

Webhooks that say what changed

A notification that something changed, with no values, forces a follow-up read for every event. On a board that is busy, that follow-up traffic is where pipelines go to die; we wrote up the follow-up-fetch spiral in detail. NovumOS deliveries carry the changed fields inline, are HMAC-signed (X-Novum-Signature: t=<unix_ts>,v1=<hex>, with the timestamp inside the signature so you can reject a replay), and are at-least-once with a stable event_id to dedupe on. A retry can never double-apply.

Identity: agents are members, not keys

Two token kinds, both bearer tokens starting with nov_, shown once and stored hashed. An agent token creates a teammate with its own name, avatar, role, and audit trail: everything it does is attributed to it in card history, @-mentions, and webhook payloads. An integration token is quicker to mint but attributes its actions to the human who owns it. A token’s permissions are capped by its owner’s current role, an agent can be scoped to a single board, and a kill switch refuses the credential outright without touching anyone else’s login. What an agent seat is covers the model.

A column as a durable queue

The part most boards do not have at all. When an automation graduates from reacting to events to working through a backlog, it needs atomic claiming, a lease with heartbeats, retry with backoff, and dead-lettering. NovumOS builds those semantics into the column:

REST (the MCP tools mirror 1:1)
POST /v1/boards/{board_id}/columns/{column_id}:claim-next
# → leases the next eligible card, returns a lease token
# renew while you work; then complete (advance) or fail (requeue)

Two workers never draft the same card, and every claim, retry, and completion stays visible to the humans watching the board. The work-queue article walks the full loop.

Price that ignores volume

Every seat, human or agent, is a flat $1 per month billed annually ($12/yr), or $3 month-to-month. Actions are unlimited, there is no per-call metering and no AI-credit meter, and your first agent is free on every plan, including the free one. Hitting the API as yourself with a personal token never costs a seat. A pipeline that does ten times the work next month costs the same next month. If a tool you are leaving queues integrations behind a low request ceiling, the rate-limit article shows what that ceiling costs a batch job in practice.

When you do not need this

If the only automation you run is a personal script that moves your own cards, any board with a token will do, and on NovumOS that is free as well. The checklist matters once the automation is shared, long-running, or acting on work other people depend on, which is the point where attribution, versioning, and queue semantics stop being nice-to-haves.

Quick answers

What should a task board API have for agents and automations?

Parity with the UI, so anything a person can do an automation can do; a stable, versioned contract; webhooks that carry the changed fields rather than a bare notification; a separate identity for each agent so writes are attributed and revocable; and rate limits and pricing that do not punish a pipeline for being busy. NovumOS meets all five: every UI capability has a REST endpoint under /v1 and a typed MCP tool, webhooks are HMAC-signed with the diff inline, agents hold their own seats, and nothing is metered per call.

Does NovumOS have a REST API and webhooks on the free plan?

Yes. The free plan is $0 forever with no card and includes the full REST API as yourself, the MCP server, HMAC-signed webhooks, unlimited boards, up to 5 human members, and one agent. Paid seats are a flat $1 per month billed annually ($3 month-to-month), the same price for humans and agents.

Can an automation claim work from a column without double-processing?

Yes. A column is a durable queue: POST /v1/boards/{board_id}/columns/{column_id}:claim-next atomically leases the next card and returns a lease token. The worker renews the lease while it works, then completes (advances the card) or fails it (requeues with backoff), so two workers never pick up the same card. The same loop exists as MCP tools: claim_next_card, renew_lease, complete_lease, fail_lease.

How do I authenticate an automation against the board?

With a bearer token that starts with nov_, minted in Workspace Settings. An agent token creates an agent teammate with its own name, avatar, role, and audit trail, so the work is attributed to the agent. An integration token is quicker but attributes its writes to the human who owns it. REST requests also send X-Board-Version: 2026-06-19 so the contract is pinned.

Mint a token and drive a real board. The free plan includes the full API, MCP, and webhooks, with no card.

Create account