> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vizapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference documentation for the VizAPI.ai REST API

# VizAPI.ai API Reference

Welcome to the VizAPI.ai API reference documentation. Our API allows you to extract structured data from images, documents, and other visual content.

## Base URL

All API requests should be made to the following base URL:

```
https://api.vizapi.ai/v1
```

## Authentication

VizAPI.ai uses API keys for authentication. You can obtain your API key from the [VizAPI.ai dashboard](https://app.vizapi.ai/dashboard).

All API requests must include your API key in the `x-api-key` header:

```
x-api-key: YOUR_API_KEY
```

<Warning>
  Keep your API key secure and never expose it in client-side code or public repositories.
</Warning>

## Request Format

API requests should be made using HTTPS with JSON-encoded bodies. Set the `Content-Type` header to `application/json`.

## Image Input

VizAPI accepts images in two formats:

1. **Image URL**: Provide a publicly accessible URL to your image.
2. **Base64 Encoded Image**: Send the image data directly in your request as a base64-encoded data URL.

For base64 encoding, use the format:

```
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...
```

### Supported Image Formats

VizAPI supports the following image formats:

* **PNG** - Portable Network Graphics
* **JPEG/JPG** - Joint Photographic Experts Group
* **GIF** - Graphics Interchange Format
* **WebP** - Modern web image format
* **TIFF** - Tagged Image File Format
* **BMP** - Windows Bitmap
* **ICO** - Windows Icon
* **SVG** - Scalable Vector Graphics
* **EPS** - Encapsulated PostScript
* **TGA** - Truevision Graphics Adapter

### Image Requirements

* **Maximum file size**: 10MB
* **Maximum dimensions**: 2048x2048 pixels (larger images will be automatically resized)
* Images must be publicly accessible if using URLs

### Supported Field Types

VizAPI supports the following field types for data extraction:

* **string** - Text values
* **number** - Numeric values (integers and decimals)
* **boolean** - True/false values
* **date** - Date values (extracted in various formats)
* **enum** - Predefined list of possible values
* **object** - Complex nested structures with subfields
* **image** - AI-generated images based on extracted data and context

### Advanced Features

#### Template Metadata Generation

When using the suggest-fields endpoint, you can request automatic generation of template metadata including title, description, category, and tags by setting `with_metadata: true`.

#### Multi-language Support

Extraction results can be translated to a target language by providing the `target_language` parameter in the advanced options.

#### Template Versioning

Templates support versioning to allow for iterative improvements while maintaining backward compatibility. When working with templates:

* If no `version_number` is specified, the latest version is automatically used
* Setting `version_number` to `0` also selects the latest version
* Specifying a specific version number (e.g., `1`, `2`, `3`) will use that exact version
* If a requested version doesn't exist, a 404 error will be returned

#### Image Field Generation

VizAPI supports generating images as part of data extraction. Image fields can include context from other extracted fields and support reference images to guide generation.

For code snippets on how to generate base64-encoded images in various programming languages, see our [Base64 Encoding Guide](/api-reference/templates/base64-encoding).

## Response Format

All responses are returned in JSON format. A typical successful response includes:

```json theme={null}
{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  }
}
```

## Error Handling

When an error occurs, the API returns an appropriate HTTP status code and a JSON response with error details:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Error message description"
  }
}
```

Common error codes include:

| Status Code | Description                                                            |
| ----------- | ---------------------------------------------------------------------- |
| 400         | Bad Request - The request was malformed or missing required parameters |
| 401         | Unauthorized - Invalid or missing API key                              |
| 404         | Not Found - The requested resource was not found                       |
| 429         | Too Many Requests - You have exceeded the rate limit for API requests  |
| 500         | Internal Server Error - An unexpected error occurred on our servers    |

## Rate Limits

VizAPI.ai implements rate limiting to ensure fair usage of the platform. The specific limits depend on your subscription plan.

When you exceed the rate limit, the API returns a `429 Too Many Requests` status code with a `Retry-After` header indicating the number of seconds to wait before making another request.

## Available Endpoints

VizAPI.ai provides the following main endpoints:

### Templates

| Endpoint                                                          | Method | Description                                                   |
| ----------------------------------------------------------------- | ------ | ------------------------------------------------------------- |
| [/templates/{template_id}](/api-reference/endpoint/templates-get) | GET    | Get a template by ID with optional version parameter          |
| [/templates](/api-reference/endpoint/templates-list)              | GET    | Get all private templates belonging to the authenticated user |

### Agents

| Endpoint                                                                | Method | Description                                          |
| ----------------------------------------------------------------------- | ------ | ---------------------------------------------------- |
| [/agents/suggest-fields](/api-reference/endpoint/agents-suggest-fields) | POST   | Analyze a document and suggest fields for extraction |
| [/agents/extract-values](/api-reference/endpoint/agents-extract-values) | POST   | Extract values from a document using a template      |

### Utility Endpoints

| Endpoint                                  | Method | Description                        |
| ----------------------------------------- | ------ | ---------------------------------- |
| [/health](/api-reference/endpoint/health) | GET    | Check the health status of the API |

## API Versioning

The VizAPI.ai API uses versioning to ensure backward compatibility. The current version is `v1`. When we make breaking changes, we'll release a new version (e.g., `v2`) while maintaining support for previous versions.

## Support

If you have any questions or need assistance with the API, please contact our support team at [support@vizapi.ai](mailto:support@vizapi.ai).