Skip to main content
The Vook API returns consistent, predictable JSON for every response — whether you’re fetching a single resource, a paginated list, or handling an error. Understanding this structure lets you write simpler parsing logic, handle edge cases confidently, and build integrations that degrade gracefully when something goes wrong.

​
Success Responses

A successful request targeting a single resource returns a response with a top-level data object containing the resource, plus a meta object with request metadata: 
{
  "data": {
    "id": "item_01J8KZ2X",
    "name": "Quarterly Report",
    "description": "Financial summary for Q3 2024",
    "tags": ["finance", "q3"],
    "status": "active",
    "created_at": "2024-11-01T12:00:00Z",
    "updated_at": "2024-11-01T14:23:11Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
Always read your resource from response.data. Do not rely on the shape of meta for business logic — its contents may be extended in future versions. 
import httpx

client = httpx.Client(
    base_url="https://api.vook.ai/v1",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

response = client.get("/items/item_01J8KZ2X")
response.raise_for_status()

item = response.json()["data"]
print(item["name"])  # "Quarterly Report"

​
List Responses

Endpoints that return collections wrap the array in data and include a pagination object to help you navigate through large result sets: 
{
  "data": [
    {
      "id": "item_01J8KZ2X",
      "name": "Quarterly Report",
      "status": "active",
      "created_at": "2024-11-01T12:00:00Z"
    },
    {
      "id": "item_01J8KZ3Y",
      "name": "Annual Summary",
      "status": "active",
      "created_at": "2024-10-15T09:30:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
Use the pagination fields to implement a fetch loop:
FieldTypeDescription
totalintegerTotal number of matching resources across all pages
limitintegerNumber of results returned in this response
offsetintegerNumber of results skipped before this page
has_morebooleantrue if there are additional results beyond this page
import httpx

client = httpx.Client(
    base_url="https://api.vook.ai/v1",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

all_items = []
offset = 0
limit = 20

while True:
    response = client.get("/items", params={"limit": limit, "offset": offset})
    response.raise_for_status()
    body = response.json()

    all_items.extend(body["data"])

    if not body["pagination"]["has_more"]:
        break

    offset += limit

print(f"Fetched {len(all_items)} items")

​
HTTP Status Codes

The Vook API uses standard HTTP status codes to indicate the outcome of every request. Your client should branch on the status code before attempting to parse the response body.
Status CodeMeaning
200 OKThe request succeeded. The response body contains the requested resource.
201 CreatedA new resource was created. The response body contains the created resource.
204 No ContentThe request succeeded but there is no response body (common for DELETE).
400 Bad RequestThe request was malformed — missing required fields or invalid JSON.
401 UnauthorizedThe API key is missing, invalid, or revoked.
403 ForbiddenThe API key is valid but does not have permission to perform this action.
404 Not FoundThe requested resource does not exist.
422 Unprocessable EntityThe request body is valid JSON but failed business-logic validation.
429 Too Many RequestsYou have exceeded your rate limit. Check the Retry-After header before retrying.
500 Internal Server ErrorAn unexpected error occurred on Vook’s side. Retry with exponential backoff.
Treat any 5xx response as transient and implement retry logic with exponential backoff. For persistent 5xx errors, check the Vook status page or contact support with your X-Request-ID.

​
Request IDs

Every response — whether successful or an error — includes an X-Request-ID header. This ID uniquely identifies your request in Vook’s systems: 
# Example response headers
HTTP/2 200
content-type: application/json
X-Request-ID: req_abc123
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
The same ID is also available in the meta.request_id field of the response body (and in error.request_id for error responses). Always include your X-Request-ID when contacting Vook support. It allows the support team to locate your specific request in logs and diagnose the issue quickly — without it, troubleshooting is significantly harder.
Log the X-Request-ID value alongside your own application logs. When an error surfaces in production, you’ll be able to correlate it directly with a specific API call.