Source
DocsChangelogStatus
Open app
OverviewCLIAgent HTTP APIPermissions

Agent HTTP API

The API the neuvikon CLI uses. Every endpoint takes a POST with a JSON body, under this base URL:

https://flexible-bird-801.eu-west-1.convex.site

Authenticating

Send your token as token in the body of every call. It belongs to one organization and carries the permissions of the person who approved it. Keep it secret.

Getting one takes a device login:

  1. POST /api/cli/auth/start with no body returns deviceCode, userCode, verifyUrl, expiresAt and intervalMs.
  2. A signed-in person opens verifyUrl and approves the code.
  3. POST /api/cli/auth/poll with deviceCode, every intervalMs. It answers status: pending, denied, expired or approved, which also carries token, userName and organizationName.

POST /api/cli/auth/revoke with token retires a token.

Referring to tickets

ticketRef is a ticket's reference, such as NS-12. It also tells the API which project you mean, so filing a new ticket still names an existing one.

Endpoints

POST /api/agent/events

Report a coding session's lifecycle and token usage.

Bodyevent (start, report, stop or error), ticketRef (required for start), sessionKey (required after start), tool (claude-code, codex, cursor or other), tokensIn, tokensOut, message
Returns{ ok, event }, plus sessionKey and startedAt on start

POST /api/agent/board

Read the columns a ticket's board really has.

BodyticketRef
Returns{ ok, currentColumn, columns: [{ name, isDone }] }

POST /api/agent/ticket

Read a ticket's full text, as a prompt for an agent.

BodyticketRef
Returns{ ok, text }

POST /api/agent/move

Move a ticket to a named column. A comment saying why is required.

BodyticketRef, column, comment
Returns{ ok, column }

POST /api/agent/comment

Leave a note on a ticket without moving it.

BodyticketRef, comment
Returns{ ok }

POST /api/agent/tickets/create

File a ticket in the same project as ticketRef, or a sub-ticket with parentRef.

BodyticketRef, title, and optionally description, type (feature, bug, chore, spike, docs), priority (low, medium, high, urgent), labels, parentRef, assignee, sprint
Returns{ ok, ref, parentRef? }

POST /api/agent/tickets/update

Change fields on a ticket. Column moves go through /api/agent/move.

BodyticketRef, and any of assignee, sprint, team, estimate, due (each null to clear), type, priority, labels, title, description
Returns{ ok, ref, changed: [field names] }

POST /api/agent/pages

Read every page in the ticket's project, as Markdown.

BodyticketRef
Returns{ ok, pages: [{ id, title, text, updatedAt }] }

POST /api/agent/pages/upsert

Create a page, or replace the one with this title.

BodyticketRef, title, text
Returns{ ok, id, created }

Errors

A refusal has a matching HTTP status and a body of { error, code? }. error is a sentence you can show a person. code appears when a program can act on the reason:

CodeStatusMeaning
invalid_token401The token is unknown or revoked.
not_a_member403The token's owner left the organization.
viewer_read_only403The token's owner holds a view-only seat.
organization_locked403The organization's subscription lapsed.

Calls are rate limited. A 429 means wait and try again.

© 2026 Neuvikon

SupportTermsPrivacySub-processorsDPATrustAccessibility