# Quick Start

Ad Center serves vzla.io banner ads to third-party applications. You fetch the currently active ads and render them in your own layout.

1. **Request an API token**

   Ad Center tokens are issued by vzla.io. To get access to the Ad Center API, contact vzla.io.

   Tokens look like this:

   ```
   vzlaio_a1b2c3d4e5f6...
   ```

2. **Make your first request**

   Pass your token in the `Authorization` header:

   ```bash
   curl --request GET \
     --url 'https://app.vzla.io/api/adcenter/v1/ads/' \
     --header 'Authorization: Bearer vzlaio_YOUR_TOKEN_HERE'
   ```

3. **Read the response**

   A successful response wraps data in the `{data, meta}` envelope:

   ```json
   {
     "data": [
       {
         "ad_id": "5edce7fa-0109-49a7-8aff-0e5eb27e9560",
         "title": "⚽ ¿Cuánto sabes realmente de fútbol?",
         "link": "https://futbble.com/descargar",
         "description": null,
         "expires_at": "2026-09-21T12:00:20-04:00"
       }
     ],
     "meta": {
       "count": 1
     }
   }
   ```

## Authentication

Every request (except [My Quota](/adcenter/v1/me/quota)) must include:

```http
Authorization: Bearer vzlaio_YOUR_TOKEN_HERE
```

Requests without a valid token return `401 Unauthorized`.

## Quota

Quotas reset on the **first day of each calendar month**. When you exceed your monthly limit the API returns `429 Too Many Requests`. Check your usage at any time with [`/me/quota/`](/adcenter/v1/me/quota), which is free and does not consume quota.

Requests are also rate limited to **1000 per hour** per token.

## Endpoints

| Endpoint | What it returns | Cache |
|---|---|---|
| [`GET /api/adcenter/v1/ads/`](/adcenter/v1/ads) | Banner ads currently being served | 5 min |
| [`GET /api/adcenter/v1/me/quota/`](/adcenter/v1/me/quota) | Your current quota status (free, no quota used) | — |

## Error format

All errors follow a standard envelope:

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid token format"
  }
}
```

| Error code | HTTP status | Meaning |
|---|---|---|
| `auth_missing` | 401 | No `Authorization` header sent |
| `auth_token_unknown` | 401 | Token not found, inactive, or malformed |
| `product_forbidden` | 403 | Token is valid but issued for a different vzla.io API |
| `quota_exceeded` | 429 | Monthly limit reached |
**Note:** Ad Center tokens are separate from Quantis tokens. A token issued for Quantis returns `403 product_forbidden` here, and an Ad Center token will not authenticate against Quantis endpoints.