Skip to main content
Every interaction with the Vook API begins with an HTTP request. To get a successful response, your requests need to carry the right headers, use the correct HTTP method, and send well-formed JSON when a body is expected. This page walks you through everything you need to construct valid requests — from authentication headers to idempotency keys for safe retries.

​
Required Headers

Include the following headers on every request to the Vook API:
HeaderValueRequired
AuthorizationBearer YOUR_API_KEYAlways
Content-Typeapplication/jsonPOST/PUT/PATCH
Acceptapplication/jsonRecommended
Authorization authenticates your request. Replace YOUR_API_KEY with a key generated in the Vook dashboard. Never expose your API key in client-side code or commit it to source control — use environment variables instead. Content-Type tells the API that your request body is JSON. Omitting this on a POST, PUT, or PATCH request will result in a 400 Bad Request. Accept signals that you expect a JSON response. While the API always returns JSON, setting this header explicitly is good practice and future-proofs your integration. 
curl https://api.vook.ai/v1/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Your API key grants full access to your Vook account. Store it securely using a secrets manager or environment variable — never hardcode it in your source code.

​
Request Body

For POST, PUT, and PATCH requests, send a JSON-encoded body describing the resource you want to create or modify. Make sure Content-Type: application/json is set; otherwise the server will not parse the body. The following example creates a new item: 
curl https://api.vook.ai/v1/items \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Quarterly Report",
    "description": "Financial summary for Q3 2024",
    "tags": ["finance", "q3"]
  }'

​
Partial Updates with PATCH

Use PATCH when you want to update only specific fields on an existing resource. You only need to include the fields you’re changing — omitted fields remain unchanged. 
curl https://api.vook.ai/v1/items/item_01J8KZ2X \
  -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quarterly Report — Final"}'

​
Query Parameters

GET requests use query parameters to filter, sort, and paginate results. Append them to the URL using standard URL encoding.

​
Pagination

ParameterTypeDefaultDescription
limitinteger20Number of results to return (max 100)
offsetinteger0Number of results to skip
# Fetch the second page of 20 items
curl "https://api.vook.ai/v1/items?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtering

Many list endpoints support field-specific filters. Pass filter values as query parameters: 
# Filter items by tag and status
curl "https://api.vook.ai/v1/items?tag=finance&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Sorting

Use sort and order to control the order of results: 
# Sort by creation date, newest first
curl "https://api.vook.ai/v1/items?sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"
Available filter, sort, and pagination parameters vary by endpoint. Refer to the individual endpoint reference for the full list of supported parameters.

​
Idempotency

Network failures happen. If your POST request times out, you may not know whether the server processed it before the connection dropped. Re-sending the same request without a safeguard could create duplicate resources. Protect against this by passing an Idempotency-Key header with a unique value (a UUID works well) on any POST request that creates or mutates state. If the API receives a second request with the same key within 24 hours, it returns the cached response from the first request instead of executing the operation again. 
curl https://api.vook.ai/v1/items \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: e6b5c3a2-91f4-4d8e-b7c1-2a3f9e0d5c88" \
  -d '{"name": "Quarterly Report"}'

import uuid
import httpx

idempotency_key = str(uuid.uuid4())

response = client.post(
    "/items",
    headers={"Idempotency-Key": idempotency_key},
    json={"name": "Quarterly Report"},
)
Generate a fresh idempotency key for each logical operation, not each HTTP attempt. Store the key alongside the pending operation so you can reuse it on retries for the same action.