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

# Overview

> Programmatic access to the ISTARI Global Organization Index (GOI) via API key.

Use it to **discover** organizations (keyword, semantic description, similarity to known domains, or filters alone), **look up** known domains in bulk, and (on eligible tiers) run **aggregations** and read **filter option** lists.

> [!TIP]
>
> **Interactive reference:** try endpoints in the [API Playground](https://docs.istari.ai/api-reference/search.md).

> [!NOTE]
>
> Don't have a key yet? Create one under [API keys](https://docs.istari.ai/goi/api-keys.md) in the GOI dashboard.

## Base URL

All GOI API paths are under:

```text theme={null}
https://api.istari.ai/v2/
```

Examples:

* `POST https://api.istari.ai/v2/search`
* `POST https://api.istari.ai/v2/fetch`

## Authentication

Every request must include your API key:

```http theme={null}
x-api-key: <your-api-key>
```

Each key has an API tier. New keys get `tier_1`; `tier_2` is available on request. Quotas and rate limits depend on your key's tier (see [Reference](https://docs.istari.ai/api/goi-reference.md#rate-limits-and-tiers)).

## Quick example : search

```bash theme={null}
curl --location 'https://api.istari.ai/v2/search' \
  --header 'Accept: application/json' \
  --header 'x-api-key: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "describe": "SaaS organizations in the US",
    "keywords": {
      "must_all": [],
      "must_any": [],
      "must_not": []
    },
    "filters": {
      "country": ["United States"],
      "state": [],
      "region": [],
      "organization_type": [],
      "organization_size": [],
      "nace_code": []
    },
    "excludes": [],
    "columns": ["domain"],
    "size": 50
  }'
```

## Endpoints at a glance

Paths are relative to **`https://api.istari.ai/v2`**.

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/search` | Search and rank organisations (modes described in [Search](https://docs.istari.ai/api/goi-search.md)) |
| `POST` | `/fetch` | Bulk lookup by domain list: no scoring ([Fetch, stats & utilities](https://docs.istari.ai/api/goi-fetch-stats.md)) |
| `POST` | `/stats` | Aggregations (`COUNT` by dimension); monthly quota by tier |
| `GET` | `/filters/options` | Allowed values for categorical filters (scoped to your key) |
| `GET` | `/locations` | Browse administrative areas for geographic filters |
| `GET` | `/locations/search` | Find the exact place name for a geographic filter |
| `GET` | `/health` | Liveness / database check |

## Documentation map

* [Search](https://docs.istari.ai/api/goi-search.md): request body, auto-detected modes, keywords, `similar_to`, `describe`, filters, pagination, deduplication
* [Fetch, stats & utilities](https://docs.istari.ai/api/goi-fetch-stats.md): `/fetch`, `/stats`, `/filters/options`, `/locations`, and health
* [Reference: columns, filters, limits & errors](https://docs.istari.ai/api/goi-reference.md): response fields, quotas, HTTP errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.