# Installgraph API

The Installgraph API tells you which apps a Shopify store runs and which stores run an app, over **16** JSON endpoints at `https://api.installgraph.com`; 1 credit unlocks 1 store, and a company email gets up to **50** free credits.

## Quickstart

You need a work email address. A browser is enough; a terminal is optional. This takes about two minutes.

### 1. Get a key

[Start free](https://installgraph.com/login) with your email and open the sign-in link we send. Your key is step 1 on your [dashboard](https://installgraph.com/account); copy it then, as it is shown once. With a company email you start with 25 free credits, and 25 more once the link is clicked (once per company domain). Keep the key in an environment variable:

```bash
export INSTALLGRAPH_API_KEY="sfs_…"
```

### 2. Count before you pay

Counts are free. How many UK stores run Klaviyo?

```bash
curl "https://api.installgraph.com/v1/apps/klaviyo/companies/count?country=GB" \
  -H "Authorization: Bearer $INSTALLGRAPH_API_KEY"
```

```json
{ "data": { "app": "klaviyo", "count": 1284 }, "meta": { "creditsUsed": 0, "creditsRemaining": 50 } }
```

### 3. Pull the rows you need

Each store in the page costs 1 credit. `limit` caps the spend.

```bash
curl "https://api.installgraph.com/v1/apps/klaviyo/companies?country=GB&limit=10" \
  -H "Authorization: Bearer $INSTALLGRAPH_API_KEY"
```

The same call in JavaScript (Node 18+) and Python:

```js
const res = await fetch("https://api.installgraph.com/v1/apps/klaviyo/companies?country=GB&limit=10", {
  headers: { Authorization: `Bearer ${process.env.INSTALLGRAPH_API_KEY}` },
});
const { data, pagination, meta } = await res.json();
console.log(data.map((s) => s.domain), meta.creditsRemaining);
```

```python
import os, requests

res = requests.get(
    "https://api.installgraph.com/v1/apps/klaviyo/companies",
    params={"country": "GB", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['INSTALLGRAPH_API_KEY']}"},
)
body = res.json()
print([s["domain"] for s in body["data"]], body["meta"]["creditsRemaining"])
```

### No code: a CSV in your browser

Add `.csv` to any endpoint and your key as `?key=`, and open the URL. The browser downloads a spreadsheet, charged the same as the JSON:

```
https://api.installgraph.com/v1/apps/klaviyo/companies.csv?country=GB&limit=10&key=sfs_…
```

Nested fields become columns (`industry.category`), and lists are joined with "; ". `limit` (up to 500) still caps the spend; the next page's cursor is in the `X-Next-Cursor` response header.

To look up one store instead: [`GET /v1/companies/{domain}`](https://installgraph.com/docs/reference/get-company.md).

## Conventions

- **Base URL:** `https://api.installgraph.com`. Every path starts with `/v1`. HTTPS only.
- **Auth:** `Authorization: Bearer sfs_…` (or `X-API-Key`) from code, or `?key=sfs_…` on a URL in a browser. See [Authentication](https://installgraph.com/docs/authentication.md).
- **CSV:** add `.csv` to any endpoint's path for a spreadsheet instead of JSON.
- **Responses:** JSON. A success is `{ "data", "meta" }`; lists add `"pagination"`. An error is `{ "error": { "code", "message", "requestId" } }`. See [Errors](https://installgraph.com/docs/errors.md).
- **Times** are ISO 8601 in UTC (`2026-11-02T03:40:12.000Z`). **Countries** are ISO 3166-1 alpha-2 (`GB`).
- **Missing values** are `null`, never omitted: every documented field is always present.
- **Freshness:** each store's homepage is scanned once a week. See [Data model](https://installgraph.com/docs/data-model.md).
- **Stability:** within `v1`, fields and error codes are added but never renamed or removed. Ignore fields you do not recognise.

## Endpoints

| Endpoint | What it returns | Cost |
| --- | --- | --- |
| [`GET /v1/companies/{domain}`](https://installgraph.com/docs/reference/get-company.md) | A store's current stack | 1 credit |
| [`GET /v1/apps/{slug}/companies`](https://installgraph.com/docs/reference/list-app-companies.md) | Stores running an app | 1 credit per store |
| [`GET /v1/apps/{slug}/companies/count`](https://installgraph.com/docs/reference/count-app-companies.md) | How many stores run an app (free) | Free |
| [`GET /v1/events`](https://installgraph.com/docs/reference/list-events.md) | Installs and removals | 1 credit per store |
| [`POST /v1/webhooks`](https://installgraph.com/docs/reference/create-webhook.md) | Subscribe to an app's installs or removals | 10 credits per change delivered |
| [`GET /v1/webhooks`](https://installgraph.com/docs/reference/list-webhooks.md) | Your webhooks | Free |
| [`GET /v1/webhooks/{id}`](https://installgraph.com/docs/reference/get-webhook.md) | One webhook | Free |
| [`DELETE /v1/webhooks/{id}`](https://installgraph.com/docs/reference/delete-webhook.md) | Delete a webhook | Free |
| [`GET /v1/webhooks/{id}/deliveries`](https://installgraph.com/docs/reference/list-webhook-deliveries.md) | Recent deliveries | Free |
| [`POST /v1/webhooks/{id}/test`](https://installgraph.com/docs/reference/test-webhook.md) | Send a sample delivery now | Free |
| [`GET /v1/apps`](https://installgraph.com/docs/reference/list-apps.md) | The app catalogue | Free |
| [`GET /v1/industries`](https://installgraph.com/docs/reference/list-industries.md) | The industry taxonomy, regions and order-value bands | Free |
| [`GET /v1/public/stats`](https://installgraph.com/docs/reference/get-public-stats.md) | App popularity by category, region and industry | Free |
| [`GET /v1/usage`](https://installgraph.com/docs/reference/get-usage.md) | Your balance and recent usage | Free |
| [`GET /v1/pricing`](https://installgraph.com/docs/reference/get-pricing.md) | Prices, packs and rules (no key) | Free |
| [`POST /v1/billing/purchase`](https://installgraph.com/docs/reference/agent-purchase.md) | Buy a credit pack on the saved card | Pack price |

## Guides

- [Authentication](https://installgraph.com/docs/authentication.md): getting a key, sending it, scopes.
- [Credits and billing](https://installgraph.com/docs/credits.md): what costs what, free re-pulls, running out.
- [Pagination](https://installgraph.com/docs/pagination.md): cursors and a loop that reads a whole list.
- [Rate limits](https://installgraph.com/docs/rate-limits.md): 60 requests a minute, headers, retrying.
- [Errors](https://installgraph.com/docs/errors.md): every code, and what to do about it.
- [Data model](https://installgraph.com/docs/data-model.md): how detection works, store status, industries, regions.
- [Using the API from an AI agent](https://installgraph.com/docs/agents.md): machine-readable docs and a safe spending loop.

## Machine-readable

- [OpenAPI 3.1 spec](https://installgraph.com/openapi.json): every public endpoint, schema and example.
- [llms.txt](https://installgraph.com/llms.txt) and [llms-full.txt](https://installgraph.com/llms-full.txt): an index, and every docs page in one Markdown file.
- Every docs page as Markdown: add `.md` to its URL, for example [/docs/authentication.md](https://installgraph.com/docs/authentication.md).

## Support

Quote the `requestId` from the response (also in the `X-Request-Id` header). For more than $1,000 or 40,000 stores in 30 days, the full dataset, or a weekly changes feed: [Talk to us](https://installgraph.com/talk-to-us).