canonical: https://jentic.com/apis/vikunja.io/vikunja

# Vikunja API

Pagination Every endpoint capable of pagination will return two headers: * `x-pagination-total-pages`: The total number of available pages for this request * `x-pagination-result-count`: The number of items returned for this request. Permissions All endpoints which return a single item (project, task, etc.) - no array - will also return a `x-max-permission` header with the max permission the user . The API exposes 153 endpoints secured with apiKey, basic authentication.

## For AI agents

Programmatically authenticate a user with openid connect, get an unsplash image. Covers 153 operations with apiKey, basic authentication.

## Scope

Does not handle payments, communications, or crm - use for identity and authentication only.

## Capabilities

- Authenticate a user with OpenID Connect
- Get an unsplash image
- Search for a background from unsplash
- Creates a new saved filter
- Updates a saved filter

## Use cases

### Identity and Authentication Operations

Use the Vikunja API to perform identity auth operations programmatically. The API provides 153 endpoints covering core functionality including authenticate a user with openid connect, get an unsplash image, get an unsplash thumbnail image.

Example prompt: Call POST `/auth/openid/{provider}/callback` to authenticate a user with openid connect

### Automated Auth Management

Automate auth operations by combining multiple Vikunja API endpoints. Agents can get an unsplash image and then get an unsplash thumbnail image in a single workflow.

Example prompt: Call GET `/backgrounds/unsplash/image/{image}` to get an unsplash image, then verify the result

### AI Agent Integration via Jentic

AI agents discover and call Vikunja API endpoints through Jentic without managing credentials directly. An agent searches for the required operation by intent, receives the matching endpoint schema, and executes the call with Jentic-managed authentication. This eliminates the need to read API documentation or handle apiKey, basic tokens manually.

Example prompt: Search Jentic for 'authenticate a user with openid connect', load the operation schema, and execute with Jentic-managed credentials

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/auth/openid/{provider}/callback` | Authenticate a user with OpenID Connect |
| GET | `/backgrounds/unsplash/image/{image}` | Get an unsplash image |
| GET | `/backgrounds/unsplash/image/{image}/thumb` | Get an unsplash thumbnail image |
| GET | `/backgrounds/unsplash/search` | Search for a background from unsplash |
| PUT | `/filters` | Creates a new saved filter |
| POST | `/filters/{id}` | Updates a saved filter |
| GET | `/filters/{id}` | Gets one saved filter |
| DELETE | `/filters/{id}` | Removes a saved filter |

## Key resources

- **Auth** — Operations for auth
- **Avatar** — Operations for avatar
- **Backgrounds** — Operations for backgrounds
- **Filters** — Operations for filters
- **Info** — Operations for info

## Why Jentic

- **Setup:** Wiring the Vikunja API by hand means choosing between its basic auth and its JWT Authorization header and threading tokens through its large task and filter surface yourself. Through Jentic you install once, import the Vikunja API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Vikunja puts the filter id in the URL path (`/filters/{id}`), so a rule can pin your agent to one filter and the operations around it. You choose the operations it may call, so a destructive one like deleting a filter is not included unless you add it.
- **Credential handling:** Your Vikunja credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a saved filter' or 'search Unsplash backgrounds', and Jentic returns the matching Vikunja operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0** — Alternative identity auth API
- **Okta** — Alternative identity auth API

## FAQ

### What authentication does the Vikunja API use?

The Vikunja API uses apiKey, basic authentication. Through Jentic, these credentials are stored encrypted in your Jentic One instance and injected at execution time, so raw secrets never enter the agent context.

### Can I authenticate a user with openid connect with the Vikunja API?

Yes. Use the POST `/auth/openid/{provider}/callback` endpoint. The API returns structured JSON responses that agents can parse and act on directly.

### What are the rate limits for the Vikunja API?

Rate limits are not specified in the OpenAPI spec. Check the vendor documentation for current limits. Through Jentic, rate limiting is handled automatically with retry logic built into the execution layer.

### How do I authenticate a user with openid connect through Jentic?

Install the Jentic SDK with pip install jentic, authenticate through Jentic One, the self-hosted execution layer, then search for 'authenticate a user with openid connect'. Jentic returns the matching Vikunja API operation with its input schema. Load the schema and execute the call - credentials are injected automatically.

### How many endpoints does the Vikunja API have?

The Vikunja API exposes 153 endpoints covering auth, avatar, backgrounds operations.

### Can I limit what my agent is allowed to do with the Vikunja API?

Yes. Because you run Jentic One yourself, your own rules decide which Vikunja operations and credentials the agent may use. Vikunja puts the filter id in the URL path (`/filters/{id}`), so a rule can pin the agent to one filter and the operations around it. You choose the operations it may call, so a destructive one like DELETE `/filters/{id}` is left out unless you add it.