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.siteAuthenticating
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:
POST /api/cli/auth/startwith no body returnsdeviceCode,userCode,verifyUrl,expiresAtandintervalMs.- A signed-in person opens
verifyUrland approves the code. POST /api/cli/auth/pollwithdeviceCode, everyintervalMs. It answersstatus:pending,denied,expiredorapproved, which also carriestoken,userNameandorganizationName.
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.
| Body | event (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.
| Body | ticketRef |
|---|---|
| Returns | { ok, currentColumn, columns: [{ name, isDone }] } |
POST /api/agent/ticket
Read a ticket's full text, as a prompt for an agent.
| Body | ticketRef |
|---|---|
| Returns | { ok, text } |
POST /api/agent/move
Move a ticket to a named column. A comment saying why is required.
| Body | ticketRef, column, comment |
|---|---|
| Returns | { ok, column } |
POST /api/agent/comment
Leave a note on a ticket without moving it.
| Body | ticketRef, comment |
|---|---|
| Returns | { ok } |
POST /api/agent/tickets/create
File a ticket in the same project as ticketRef, or a sub-ticket with parentRef.
| Body | ticketRef, 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.
| Body | ticketRef, 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.
| Body | ticketRef |
|---|---|
| Returns | { ok, pages: [{ id, title, text, updatedAt }] } |
POST /api/agent/pages/upsert
Create a page, or replace the one with this title.
| Body | ticketRef, 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:
| Code | Status | Meaning |
|---|---|---|
invalid_token | 401 | The token is unknown or revoked. |
not_a_member | 403 | The token's owner left the organization. |
viewer_read_only | 403 | The token's owner holds a view-only seat. |
organization_locked | 403 | The organization's subscription lapsed. |
Calls are rate limited. A 429 means wait and try again.