---
title: Quickstart
description: Get an API key, make your first call, and run your first scan with the Zaraftis v1 API.
sidebar:
  label: Quickstart
  order: 1
---

Zaraftis measures how a brand appears in AI search answers on ChatGPT, Gemini, Google AI Overview and AI Mode, Copilot, and Grok. You send prompts your buyers ask, Zaraftis asks each AI platform, and you get back whether your brand was mentioned, where, next to which competitors, and which pages were cited. Paid work uses prepaid credits.

## 1. Get an API key

Sign up for Zaraftis and choose the API path. This starts the free trial, which puts trial credits in your wallet, and creates your first API key. Copy the key from the developer page: it is shown once. Then set it in your shell:

```bash
export ZARAFTIS_API_KEY="your-api-key"
```

Keep the key on your server. Do not put it in browser code or commit it.

## 2. Check the key

This call is free. It returns the key's name, scopes, and workspace:

```bash
curl https://api.zaraftis.com/v1/me \
  --header "Authorization: Bearer $ZARAFTIS_API_KEY"
```

```json
{
  "success": true,
  "data": {
    "credential": {
      "id": "8a6f2b1c-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
      "kind": "api_key",
      "name": "Production server",
      "scopes": ["brands:read", "scans:read", "scans:write", "billing:read"],
      "brand_allowlist": []
    },
    "workspace": { "organization_id": "Ys3kQ0aN7rTbV1mW" }
  },
  "request_id": "d3b0e28f-89a4-4c1c-a68b-11b0d5886f45"
}
```

## 3. Start a scan

This scan creates the brand and asks two prompts on ChatGPT and Gemini, so it runs four queries. Read the price per query from `GET /v1/capabilities` or [Credits and billing](/credits).

```bash
curl https://api.zaraftis.com/v1/scans \
  --request POST \
  --header "Authorization: Bearer $ZARAFTIS_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "new_brand": { "url": "https://www.example.com" },
    "country": "US",
    "language": "en",
    "platform_ids": ["chatgpt", "gemini"],
    "prompts": [
      { "text": "What is the best project management tool for small agencies?" },
      { "text": "Which CRM is easiest to set up for a five-person sales team?" }
    ]
  }'
```

The API answers `202 Accepted` right away with a `scan_id`, a `task_url` to poll, and a `billing` object with the credits it reserved. If the request times out, send it again with the same `Idempotency-Key`: the scan runs and is charged only once.

## 4. Get the results

Poll the task every few seconds until its `status` is `completed`, `partial`, `failed`, or `cancelled`:

```bash
curl https://api.zaraftis.com/v1/tasks/$TASK_ID \
  --header "Authorization: Bearer $ZARAFTIS_API_KEY"
```

Then read the results:

- `GET /v1/scans/{scan_id}/metrics` for visibility, mentions, and positions.
- `GET /v1/scans/{scan_id}/observations` for each AI answer, and `GET /v1/scans/{scan_id}/citations` for the pages it cited.

To measure one prompt and wait for the answer in the same call, use `POST /v1/visibility/checks`.

## If the request fails

| Status | What to do |
| --- | --- |
| `401` | The key is missing or wrong. Check the `Authorization` header. |
| `403` | The key lacks a scope, such as `scans:write`. Create a key with that scope. |
| `400` | Read `error.field_errors`, fix the request, and do not retry it unchanged. |
| `402` | The wallet has no credits or not enough. See [Credits and billing](/credits). |
| `429` | Wait the `Retry-After` seconds, then retry. |

[Errors](/errors) covers every error code.

## Next steps

- [How requests work](/conventions): response shape, paging, retries, long-running work, and rate limits.
- [Production checklist](/best-practices): what to set up before real traffic.
- [API reference](/api): every route with its parameters and responses.