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

# Quickstart

> First successful API call in three minutes.

## 1 · Get an API key

Sign in to [verseodin.com/dashboard](https://verseodin.com/dashboard),
open **Settings → API keys**, click **Generate key**.

Copy the `vso_…` value out of the modal **immediately** — it's shown
exactly once. If you lose it, revoke and generate a new one.

<Warning>
  Anyone with your key can read every metric on every universe you own
  (and call your Claude / MCP connector). Store it like a database
  password — env vars, secrets manager, never committed to git.
</Warning>

## 2 · Make your first call

The discovery endpoint is the cheapest way to confirm auth works:

<CodeGroup>
  ```bash curl theme={null}
  curl -H "Authorization: Bearer vso_xxx" \
    https://verseodin.com/api/v1/metrics
  ```

  ```python python theme={null}
  import os, requests

  KEY = os.environ["VERSEODIN_API_KEY"]
  r = requests.get(
      "https://verseodin.com/api/v1/metrics",
      headers={"Authorization": f"Bearer {KEY}"},
      timeout=10,
  )
  r.raise_for_status()
  print(r.json()["data"][:5])
  ```

  ```javascript node theme={null}
  const KEY = process.env.VERSEODIN_API_KEY;
  const r = await fetch("https://verseodin.com/api/v1/metrics", {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  const { data } = await r.json();
  console.log(data.slice(0, 5));
  ```
</CodeGroup>

Expected response — a list of every metric column you can query:

```json theme={null}
{
  "data": [
    "ai_trust_mentions",
    "ai_avg_trust_position",
    "geo_competitor_analysis",
    "prompts_rows",
    "..."
  ]
}
```

## 3 · List your universes

```bash theme={null}
curl -H "Authorization: Bearer vso_xxx" \
  https://verseodin.com/api/v1/universes
```

The `id` field on each entry is what you'll pass to every other
endpoint:

```json theme={null}
{
  "count": 3,
  "universes": [
    {
      "id": "7f45877a-0e8e-498f-bd7f-5e70ef65a2de",
      "universe_name": "Verseodin",
      "website": "https://verseodin.com/",
      "status": "completed",
      "latest_day": "2026-04-27"
    }
  ]
}
```

## 4 · Pull a metric

Pick a universe, pick a metric, pick a day:

```bash theme={null}
curl -H "Authorization: Bearer vso_xxx" \
  "https://verseodin.com/api/v1/universes/<id>/metrics/ai_avg_trust_position?day=2026-04-27"
```

```json theme={null}
{
  "metric": "ai_avg_trust_position",
  "results": [
    { "day": "2026-04-27", "engine": "chatgpt", "value": 9 }
  ]
}
```

## 5 · Pull the AI answer + citations for a prompt

```bash theme={null}
curl -H "Authorization: Bearer vso_xxx" \
  "https://verseodin.com/api/v1/universes/<id>/prompts?day=2026-04-27&status=completed&limit=3"
```

The `data[].response_text` field contains the full AI answer body,
and `data[].my_citations` / `data[].competitor_citations` carry the
URLs the AI cited.

## What's next

<CardGroup cols={2}>
  <Card title="Authentication" href="/authentication">
    Header format, key rotation, leak playbook.
  </Card>

  <Card title="Rate limits" href="/rate-limits">
    60 req/min/key. Headers and 429 handling.
  </Card>

  <Card title="Errors" href="/errors">
    Stripe-style envelope. Status code → error type table.
  </Card>

  <Card title="Data model" href="/concepts/data-model">
    Universes → history → prompts. Where each column comes from.
  </Card>
</CardGroup>