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

# API Overview

> Read your workspace's AI visibility, content map and content data with an API key

The AeoNut API lets your scripts, dashboards and AI assistants read the data AeoNut already collects for your workspace. That includes your AI visibility, your competitors, the sources AI answers cite, your content map and your content library.

<Info>
  Every read is free, and nothing in the API spends credits today.
</Info>

## Base URL

```
https://services.deepsmith.ai/core/api/external/v1
```

All the paths in these docs are relative to this base URL, so `/me` means the base URL with `/me` on the end.

## Quick start

<Steps>
  <Step title="Create an API key">
    Go to **Settings → API keys** and click **Create key**. Give it a name and pick an expiry. New keys get all five scopes by default, and you can remove the ones you don't need.
  </Step>

  <Step title="Copy the key">
    We only show the key **once**, so copy it right away and keep it in an environment variable or a secrets manager.
  </Step>

  <Step title="Make your first request">
    You can call `/me` to check that the key works:

    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_API_KEY" \
      https://services.deepsmith.ai/core/api/external/v1/me
    ```
  </Step>
</Steps>

<Warning>
  Only workspace owners can create and revoke keys. A key acts as the person who created it, so if that person leaves the workspace, the key stops working.
</Warning>

## Authentication

Send your key with every request in either of these headers:

```
Authorization: Bearer YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
```

Each key belongs to one workspace, which is why you won't see a workspace ID in any path. Every key starts with `ds_live_`, and in the examples on this page you'd put your whole key where it says `YOUR_API_KEY`. AeoNut only stores a hash of the key, so if you lose one we can't get it back for you. In that case you can revoke it and create a new one. A revoked key stops working on the very next request.

## Scopes

Each key has scopes, and they decide which endpoints the key can call. The API only reads data, so every scope is free to use.

| Scope | Grants |
| - | - |
| `workspace:read` | `/workspace`: workspace details, plan and usage |
| `visibility:read` | `/visibility`: setup, mention and citation rates, competitors, cited pages, answers and exports |
| `contentmap:read` | `/content-map`: topics, sites and pages |
| `content:read` | `/content`: articles and ideas |
| `iq:read` | `/iq`: products, personas, brand voice, content types and visual guidelines |

Each scope unlocks one path prefix. `GET /me` works with any key, whatever scopes it has.

<Tip>
  It helps to give each integration its own key with only the scopes it needs. That way you can revoke one key without breaking the others.
</Tip>

## Response format

Every response comes back in the same wrapper:

```json theme={null}
{
  "code": 4020,
  "messages": "Key details",
  "data": { }
}
```

| Field | Description |
| - | - |
| `code` | AeoNut status code |
| `messages` | Human-readable message |
| `data` | The payload, or `null` on error |

All rates are fractions between 0 and 1, so a mention rate of `0.42` means 42%.

## Errors

The API uses the standard HTTP status codes.

| HTTP | `code` | Meaning | What to do |
| - | - | - | - |
| `401` | `4021` | Missing API key | Add the `Authorization` or `X-API-KEY` header to the request. |
| `401` | `4022` | Invalid, revoked or expired API key | Check that you copied the whole key. If it was revoked or has expired, create a new one. |
| `402` | `1916` | The workspace has no active subscription, or a payment is past due | Renew the plan or fix the payment method in Settings → Billing. `/me` and `/workspace` keep working. |
| `403` | `4023` | The key lacks a scope this endpoint needs | Create a key that has the scope listed in `missing`. |
| `404` | | The resource doesn't exist in this workspace | Check the ID. It has to come from the same workspace as the key. |
| `422` | | Invalid parameters | Check the parameter names and values against the endpoint's reference page. |
| `429` | | Rate limit exceeded | Wait a few seconds and try again. See [Rate limits](#rate-limits). |

When you get a `403`, the response tells you which scopes the key is missing:

```json theme={null}
{
  "code": 4023,
  "messages": "This API key does not have the scope required for this request.",
  "data": {
    "required": ["visibility:read"],
    "missing": ["visibility:read"]
  }
}
```

## Rate limits

You can make **120 requests per minute** per workspace, and that limit is shared across all of the workspace's keys. If you go over it, the API returns a `429`. When that happens, wait a few seconds before you try again, and wait a little longer each time if it keeps happening.

## Next steps

<CardGroup cols={2}>
  <Card title="Connect an AI assistant" icon="robot" href="/mcp/overview">
    Use the AeoNut MCP server with Claude, Cursor or VS Code.
  </Card>
</CardGroup>


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