API getting started

The GVenta Kanban Board REST API exists so that automation, AI agents, CI pipelines, internal tools and client portals can do everything a human can do in the interface. It is not a partial, read-only mirror: it creates, updates, moves, assigns, comments, replies, reacts, attaches, completes and deletes.

Basics

Base path	https://your-instance.example/api/v1
Authentication	Authorization: Bearer <token>
Request bodies	application/json, except file uploads, which are multipart/form-data
Responses	JSON, always wrapped in the envelope below

Each customer’s instance runs on its own domain, so replace your-instance.example with your instance’s hostname.

A first call to confirm your token works:

GET /api/v1/me HTTP/1.1
Host: your-instance.example
Authorization: Bearer <token>
Accept: application/json

It returns your user ID, name, email, role and the token’s abilities.

Response envelope

Every response uses the same shape.

Success:

{ "success": true, "data": { }, "meta": { } }

Error:

{ "success": false, "error": "VALIDATION_ERROR", "message": "Title is required" }

data carries the result, meta carries things like pagination totals and unread counts, and on failure error is a stable machine-readable code with a human-readable message.

Error codes

Code	HTTP status	Meaning
UNAUTHORIZED	401	Missing, malformed, expired or revoked token, or the owning user is inactive
FORBIDDEN	403	The token owner is not permitted to do this
NOT_FOUND	404	The resource does not exist or is not accessible
VALIDATION_ERROR	400	The request was understood but a value is missing or invalid
INVALID_INPUT	400	The request body could not be interpreted
UPLOAD_ERROR	400	A file upload failed validation
SERVER_ERROR	500	Something went wrong on the server

Bulk story creation returns 207 Multi-Status when some items succeeded and others failed, with per-item results; see API examples.

A missing or malformed Authorization header returns 401 with a WWW-Authenticate: Bearer header and a message explaining the expected format.

Tokens and abilities

Tokens are managed through the token endpoints. A token belongs to the user who created it and acts with that user’s permissions.

Method	Endpoint	Purpose
GET	/api/v1/me	Current identity: user ID, name, email, role and token abilities
GET	/api/v1/tokens	List your tokens (values truncated)
POST	/api/v1/tokens	Create a token: name, optional abilities, optional expires_at
DELETE	/api/v1/tokens/{id}	Revoke a token

Abilities

Each token carries an ability list:

• read permits retrieval.
• write permits mutation.
• admin implicitly grants everything.

Lifecycle

• Tokens have a name and an optional expiry date. An expired token is refused.
• A last_used_at timestamp is stamped on the token every time it authenticates successfully, so you can see which tokens are live.
• A token belonging to a deactivated user stops working immediately.
• Listing tokens returns only the first eight characters of each value. The full token value is shown exactly once, at creation, with an explicit warning that it will not be shown again. Store it somewhere safe at that moment.

Why it matters: Give each agent or integration its own named, scoped, expiring token, and revoke it without touching anything else when the integration is retired.

Access control is not bypassed

The API enforces the same access rules as the interface. Every list, search and work-queue endpoint filters results to the token owner’s accessible projects, exactly as the interface does for that same user. A token owned by a restricted user sees only that user’s projects; see Roles and access control. Assignment validation, vocabulary validation, cycle prevention and the other integrity rules apply to API writes too, returning VALIDATION_ERROR where the interface would simply not offer the option.

Pagination

Two pagination styles are in use.

• limit and offset on most list endpoints, for example GET /api/v1/stories. limit has a maximum of 500.
• page and per_page on the deep search endpoint, GET /api/v1/stories/search.

Some endpoints have their own caps: GET /api/v1/work/next defaults to 5 and allows at most 20, GET /api/v1/work/upcoming looks ahead 7 days by default and at most 30, and GET /api/v1/activity returns up to 200 entries.

Uploads

File uploads use multipart/form-data rather than JSON and pass through the full validation pipeline described in File handling and security. A rejected file returns UPLOAD_ERROR with a plain-English message. Uploading to a comment accepts at most 5 files per call. Download endpoints stream the file through your instance’s own domain; they never redirect to storage.

Explore the endpoints

The complete endpoint reference, grouped by projects, swim lanes, stories, epics, dependencies, tasks, comments, watchers, attachments, users, work queues, search and Pulse, is at /docs/kanban-board/api/. Worked request and response examples are on API examples.