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

# Quickstart

> Create a key, validate it, and make your first request.

This guide takes you from no key to your first data, in four steps.

## Prerequisites

* A Geoptie account with an active or trialing subscription
* At least one brand set up in the dashboard
* Basic familiarity with REST APIs

## Step 1: Create your API key

1. Go to **API keys** in the dashboard sidebar.
2. Click **Create API key**.
3. Choose whether the key covers your whole workspace or specific brands. See
   [Authentication](/docs/authentication) for the difference.
4. Copy the key and store it securely.

<Warning>
  The key is shown only once. Store it in a secret manager or an environment variable, and
  never commit it to version control.
</Warning>

## Step 2: Authenticate your requests

Send the key as a bearer token in the `Authorization` header:

```bash theme={null}
curl -sS "https://api.geoptie.com/v1/brands" \
  -H "Authorization: Bearer $GEOPTIE_API_KEY"
```

## Step 3: Make your first request

`GET /v1/brands` both proves the key works and returns the brand ids the other endpoints
need. Most endpoints are scoped to a brand, so this is where every integration starts.

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS "https://api.geoptie.com/v1/brands" \
    -H "Authorization: Bearer $GEOPTIE_API_KEY"
  ```

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

  r = requests.get(
      "https://api.geoptie.com/v1/brands",
      headers={"Authorization": f"Bearer {os.environ['GEOPTIE_API_KEY']}"},
      timeout=30,
  )
  r.raise_for_status()
  print(r.json())
  ```

  ```javascript Node theme={null}
  const r = await fetch("https://api.geoptie.com/v1/brands", {
    headers: { Authorization: `Bearer ${process.env.GEOPTIE_API_KEY}` },
  });
  if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
  console.log(await r.json());
  ```
</CodeGroup>

**Success response:**

```json theme={null}
{
  "data": [
    {
      "id": "8378af29-86b3-4943-9309-5b487511e88d",
      "name": "Geoptie",
      "domain": "geoptie.com",
      "category": "SaaS",
      "aliases": [],
      "engines": ["chatgpt", "claude", "perplexity", "gemini"],
      "country": "US",
      "created_at": "2026-03-14T10:22:41Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Take the `id` and use it with the brand endpoints:

<CardGroup cols={2}>
  <Card title="Visibility" icon="chart-line">
    `GET /v1/brands/{id}/visibility`
  </Card>

  <Card title="Prompts" icon="list">
    `GET /v1/brands/{id}/prompts`
  </Card>

  <Card title="Citations" icon="quote-left">
    `GET /v1/citations?brand_id={id}`
  </Card>

  <Card title="Competitors" icon="users">
    `GET /v1/competitors?brand_id={id}`
  </Card>
</CardGroup>

## Error handling

The API uses standard HTTP status codes:

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| 200    | Success                                    |
| 400    | Bad request, check your parameters         |
| 401    | Invalid or missing API key                 |
| 402    | Subscription inactive or past due          |
| 403    | Your plan or key does not allow this       |
| 404    | Not found, or not accessible with this key |
| 429    | Rate limit reached                         |
| 500    | Something went wrong on our side           |

See [Errors](/docs/errors) for the full list of codes.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/authentication">
    Key types and access
  </Card>

  <Card title="Pagination" icon="arrow-right" href="/docs/pagination">
    Walking large result sets
  </Card>
</CardGroup>

## Need help

Email [support@geoptie.com](mailto:support@geoptie.com) with the `X-Request-Id` from the
failing response.