# Simplitas API

The Simplitas API lets you run AI Visibility Checks — scanning ChatGPT, Perplexity, and Google AI
against real buyer prompts for a keyword — and read back the results, from your own code instead
of the app.

This document is also served as plain text at `/api-docs.md`, so you can hand the whole thing to
an LLM or fetch it from a script.

## Base URL

```
https://www.simplitas.com/api/v1
```

## Authentication

Every request needs an API key in the `Authorization` header:

```
Authorization: Bearer smpl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Generate a key from **Developers** inside the app: [simplitas.com/app/developers](https://www.simplitas.com/app/developers).
The full key is shown once, at creation — Simplitas only ever stores its hash, so if you lose it
you'll need to create a new one and revoke the old one.

A key belongs to your organization, not to the person who created it: any key on the account can
read and write the same data, and teammates all see the same keys under Developers.

Requests without a valid, unrevoked key get:

```json
{ "error": "Invalid or missing API key" }
```

with HTTP status `401`.

## Resources

### Visibility Checks

A visibility check runs ~100 AI-generated buyer prompts about a keyword through ChatGPT and
records which brands show up, and where. Creating one is asynchronous — prompts are generated and
saved immediately, then the scan itself runs in the background over the next few minutes. Poll the
check until `status` is `"complete"`.

#### `POST /visibility-checks`

Start a new check.

**Body**

| Field          | Type   | Required | Description                                  |
|----------------|--------|----------|-----------------------------------------------|
| `keyword`      | string | yes      | What buyers are shopping for, e.g. `"CRM software"`. Max 120 characters. |
| `brand_name`   | string | no       | Your brand, so the response can report its position in each answer. |
| `brand_domain` | string | no       | Your domain, used the same way as `brand_name`. |

```bash
curl -X POST https://www.simplitas.com/api/v1/visibility-checks \
  -H "Authorization: Bearer smpl_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "CRM software", "brand_name": "Acme", "brand_domain": "acme.com"}'
```

**Response** — `202 Accepted`

```json
{
  "id": "b3b9b5f0-...",
  "keyword": "CRM software",
  "promptCount": 100,
  "status": "running",
  "createdAt": "2026-09-08T12:00:00.000Z"
}
```

#### `GET /visibility-checks`

List checks for your organization, newest first.

**Query parameters**

| Param   | Type   | Default | Description                     |
|---------|--------|---------|----------------------------------|
| `limit` | number | 20      | Max results to return (1-100).  |

```bash
curl https://www.simplitas.com/api/v1/visibility-checks?limit=10 \
  -H "Authorization: Bearer smpl_live_xxxx"
```

**Response** — `200 OK`

```json
{
  "data": [
    {
      "id": "b3b9b5f0-...",
      "keyword": "CRM software",
      "brandName": "Acme",
      "brandDomain": "acme.com",
      "promptCount": 100,
      "completedCount": 100,
      "status": "complete",
      "createdAt": "2026-09-08T12:00:00.000Z"
    }
  ]
}
```

#### `GET /visibility-checks/{id}`

Fetch one check's full results: every prompt's answer, and a leaderboard of every brand that
showed up across them.

```bash
curl https://www.simplitas.com/api/v1/visibility-checks/b3b9b5f0-... \
  -H "Authorization: Bearer smpl_live_xxxx"
```

**Response** — `200 OK`

```json
{
  "check": {
    "id": "b3b9b5f0-...",
    "keyword": "CRM software",
    "brandName": "Acme",
    "brandDomain": "acme.com",
    "promptCount": 100,
    "completedCount": 100,
    "status": "complete",
    "createdAt": "2026-09-08T12:00:00.000Z"
  },
  "results": [
    {
      "prompt": "Which CRM software is best for a 10-person sales team?",
      "sequenceNumber": 1,
      "brands": [{ "rank": 1, "name": "Acme" }, { "rank": 2, "name": "Competitor" }],
      "sources": [{ "url": "https://...", "name": "...", "snippet": "..." }],
      "brandPosition": 1
    }
  ],
  "leaderboard": [{ "name": "Acme", "mentions": 42, "avgPosition": 1.8 }]
}
```

A check you didn't create — wrong ID, or one belonging to a different organization — returns
`404`.

### Tracked Keywords

Keywords with "Track daily" turned on in the app get rescanned automatically. The API can list
them and flip that switch, but not create new tracked keywords directly — a keyword starts being
tracked the first time a signed-in user runs a check for it in the app.

#### `GET /tracked-keywords`

```bash
curl https://www.simplitas.com/api/v1/tracked-keywords \
  -H "Authorization: Bearer smpl_live_xxxx"
```

**Response** — `200 OK`

```json
{
  "data": [
    {
      "id": "9f1c...",
      "keyword": "CRM software",
      "brandName": "Acme",
      "brandDomain": "acme.com",
      "enabled": true,
      "lastRunAt": "2026-09-08T06:00:00.000Z",
      "createdAt": "2026-08-01T09:00:00.000Z"
    }
  ]
}
```

#### `PATCH /tracked-keywords/{id}`

Enable or disable daily tracking for one keyword.

**Body**

| Field     | Type    | Required | Description                    |
|-----------|---------|----------|----------------------------------|
| `enabled` | boolean | yes      | `true` to track, `false` to stop. |

```bash
curl -X PATCH https://www.simplitas.com/api/v1/tracked-keywords/9f1c... \
  -H "Authorization: Bearer smpl_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

**Response** — `200 OK`

```json
{ "id": "9f1c...", "keyword": "CRM software", "enabled": false }
```

## Errors

Every error response is a JSON object with a single `error` string:

```json
{ "error": "Missing keyword" }
```

| Status | Meaning                                              |
|--------|-------------------------------------------------------|
| `400`  | The request body or query string is missing or invalid. |
| `401`  | The API key is missing, malformed, or revoked.         |
| `404`  | The resource doesn't exist, or belongs to another organization. |
| `500`  | Something went wrong on our end.                       |
| `502`  | The upstream AI provider failed to generate a usable response — try again. |

## Fair use

There's no hard rate limit yet, but a `visibility-checks` scan costs real API calls on our end
(AI models write the prompts and run the scan) — keep automated check creation
to what you'd reasonably run by hand. If you need a specific volume, get in touch.

## Feature coverage

This API currently covers AI Visibility Checks and tracked-keyword management. It does not cover
every feature in the Simplitas app (AI Brand Mentions outreach, AI Humanizer, GEO Content, and the
CRM are app-only for now) — if you need one of those as an API, let us know.

## Using this from Claude

Everything above is also available as a Claude connector — a remote MCP server at `/api/mcp` that
wraps these same endpoints. It supports both a real sign-in (OAuth) and the static API key shown
above. See [/claude-connector](/claude-connector) for setup.