Skip to main content
This guide walks you through a complete Vook API integration from scratch. By the end, you’ll have a working setup that authenticates with the API, makes requests, parses JSON responses, and handles errors gracefully — giving you a solid foundation to build on.

​
Prerequisites

Before you begin, make sure you have the following:
  • A Vook account — sign up at app.vook.ai
  • A Vook API key — find yours in Settings → API Keys after logging in
  • Basic familiarity with HTTP and REST APIs
  • Python 3.8+ or Node.js 18+ installed on your machine
Keep your API key out of source code and version control. Store it as an environment variable and read it at runtime — never hard-code it in your application.

​
Step-by-Step Integration

1

Set up your environment

Install an HTTP client library and store your API key as an environment variable so it’s available to your code without being hard-coded.
# Python
pip install requests

# Node.js (built-in fetch is available in Node 18+, or install node-fetch)
npm install node-fetch
Set your API key in your shell or in a .env file:
export VOOK_API_KEY="your_api_key_here"
For local development, use a .env file with a library like python-dotenv or dotenv for Node.js:
# .env
VOOK_API_KEY=your_api_key_here

# main.py
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.environ["VOOK_API_KEY"]
2

Make your first authenticated request

Every Vook API request requires your API key in the Authorization header as a Bearer token. Start with a simple GET request to the root endpoint to confirm your credentials are working.
cURL
curl -X GET https://api.vook.ai/v1/ \
  -H "Authorization: Bearer $VOOK_API_KEY" \
  -H "Content-Type: application/json"
A successful response looks like:
{
  "status": "ok",
  "version": "1.0.0",
  "message": "Welcome to the Vook API"
}

import requests
import os

api_key = os.environ["VOOK_API_KEY"]
base_url = "https://api.vook.ai/v1"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.get(f"{base_url}/", headers=headers)
print(response.status_code)
print(response.json())
3

Parse the response

The Vook API always returns JSON. Read the response body and access fields directly from the parsed object.
import requests
import os

api_key = os.environ["VOOK_API_KEY"]
base_url = "https://api.vook.ai/v1"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.get(f"{base_url}/resources", headers=headers)
body = response.json()

# Access the list of resources
resources = body["data"]
for resource in resources:
    print(f"ID: {resource['id']}, Name: {resource['name']}")

# Read pagination metadata
pagination = body["pagination"]
print(f"Showing {len(resources)} of {pagination['total']} total results")
4

Handle errors

The Vook API uses standard HTTP status codes. Always check the response status before processing the body, and handle common error cases like 401 Unauthorized, 404 Not Found, and 429 Too Many Requests.
import requests
import os

api_key = os.environ["VOOK_API_KEY"]
base_url = "https://api.vook.ai/v1"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

try:
    response = requests.get(f"{base_url}/resources/res_123", headers=headers)

    if response.status_code == 200:
        resource = response.json()["data"]
        print(f"Found resource: {resource['name']}")

    elif response.status_code == 401:
        raise Exception("Invalid API key. Check your VOOK_API_KEY environment variable.")

    elif response.status_code == 404:
        print("Resource not found.")

    elif response.status_code == 429:
        retry_after = response.headers.get("Retry-After", "unknown")
        print(f"Rate limit hit. Retry after {retry_after} seconds.")

    else:
        error = response.json()
        raise Exception(f"API error {response.status_code}: {error.get('message', 'Unknown error')}")

except requests.exceptions.ConnectionError:
    print("Network error — check your internet connection.")
5

Go further

You’ve made your first authenticated request and handled errors — great start. Here are the next steps to build a production-ready integration:

Pagination

Learn how to page through large result sets efficiently using limit and offset.

Webhooks

Receive real-time event notifications instead of polling the API.

Rate Limits

Understand rate limit tiers and implement exponential backoff.