API: basics

The VentionDesk API is the same one the interface uses. For automations — Claude, your own scripts, CI — you sign in with an API key. All URLs start with https://api.ventiondesk.com; all bodies and responses are JSON in UTF-8.

Signing in with an API key

The owner creates a key under Settings › API keys › “New key”. It appears exactly once in plain text.

Every request carries it as a bearer token:

curl https://api.ventiondesk.com/v1/tasks?status=todo \
  -H "Authorization: Bearer vd_live_…"

There is no separate endpoint for exchanging it: VentionDesk recognises the key by its prefix, checks it on every request (revoked? expired?) and then works with a session for the key’s account. The same database rules therefore apply to the key as to a person — it only sees what its scope allows.

Instead of a key, the sign-in of an AI app connected via OAuth can also come as a bearer token. It counts like an agent key with the permissions and projects the person chose at consent — never with the person’s own permissions — and ends immediately when disconnected.

An agent key is an account of its own with the role Agent. It is meant for the endpoints that show a scope in the API reference, plus GET /v1/me and the agent runs. Endpoints that require “owner” or “owner and staff members” are served by the web interface with the session of a signed-in person; to an API key they answer with 403.

Scopes

What an agent key may do is determined by its scopes:

A scope appears on exactly the endpoints that honour it — the API reference names it per endpoint. deployments:read appears on no endpoint: it takes effect through the database rules of the mirrored commits, pull requests and deployments.

Project binding

A key applies to all projects or to a selection. A bound key only sees data of its projects — and deliberately nothing without a project, such as tickets not yet assigned to any project. The API answers a row outside its projects with 404 or 403. An intake key is always bound to exactly one project.

Changing the scope needs no new key. The owner changes scopes and projects under “Permissions” in the key list; the next request already works with the new scope. A revoked or expired key is rejected on its next request.

Errors

Every error response has the same shape:

{ "ok": false, "error": "Diese Aufgabe gibt es nicht.", "code": "not_found" }

error is a sentence for people (in the language from Accept-Language, German without that header), code a stable English value for programs. Common responses:

Every response carries an ID in the x-request-id header. If you send one yourself (up to 128 characters), it is used. Give it to support when something goes wrong.

Rate limits

Counted per minute, per key or per IP address:

Above the limit, the API answers with 429 and rate_limited; the RateLimit and RateLimit-Policy headers state the current count and the limit.

Lists and filters

List endpoints filter via query parameters and limit with limit; there are no pages with cursor or offset. Examples:

• GET /v1/tasks?projectSlug=shop&status=todo&claimable=true&limit=20 — tasks that can be pulled right now.
• GET /v1/projects?status=active — active projects.

Which parameters an endpoint knows and which fields it returns is listed in the API reference — read from the same contract VentionDesk uses to check the request.

The typical round of an agent

1. GET /v1/tasks?claimable=true — what needs doing?
2. POST /v1/tasks/:id/claim — claim the task atomically. Two runs never get the same one.
3. Work; in between, POST /v1/tasks/:id/result with "state": "arbeitet" as a sign of life.
4. POST /v1/tasks/:id/result with kontrolle, frage, master, blockiert or erledigt — with kontrolle and erledigt, with evidence in evidence.

If you don’t want to build this yourself, use Claude and MCP.