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

# CogNerd REST API — Overview, Formats, and Endpoints

> Base URL, request format, response structure, error codes, credit costs, and a full index of CogNerd API endpoint groups with links to detailed pages.

The CogNerd REST API gives you programmatic access to everything the platform can do — brand analysis, GEO file generation, AI-optimized content creation, and AEO audits. All requests go to a single base URL, use JSON bodies, and follow a consistent response format. You authenticate with a Bearer token obtained at login.

## Base URL

All API requests use this base URL in production:

```
https://api.cognerd.in
```

Every endpoint path below is relative to this base. For example, the full URL for the login endpoint is `https://api.cognerd.in/api/auth/login`.

<Note>
  The sandbox and staging environments use different base URLs. Contact support to obtain a non-production base URL if you need one.
</Note>

## Request format

Send all request bodies as JSON and include the `Content-Type: application/json` header.

```bash theme={null}
curl -X POST https://api.cognerd.in/api/brand-monitor/scrape \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"url": "https://acme.com"}'
```

## Response format

Successful responses return a JSON object with a `2xx` status code. The shape of the body varies by endpoint and is documented on each endpoint's page.

Error responses always follow this structure:

```json theme={null}
{
  "error": {
    "message": "Human-readable description of the error",
    "code": "ERROR_CODE",
    "statusCode": 401,
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}
```

| Field              | Type   | Description                                                 |
| ------------------ | ------ | ----------------------------------------------------------- |
| `error.message`    | string | A plain-English explanation suitable for logging or display |
| `error.code`       | string | A machine-readable error code (see common codes below)      |
| `error.statusCode` | number | The HTTP status code                                        |
| `error.timestamp`  | string | ISO 8601 timestamp of when the error occurred               |

### Common error codes

| Code                   | HTTP status | Meaning                                                   |
| ---------------------- | ----------- | --------------------------------------------------------- |
| `UNAUTHORIZED`         | 401         | Missing or invalid authentication token                   |
| `FORBIDDEN`            | 403         | Token is valid but you lack permission for this resource  |
| `NOT_FOUND`            | 404         | The requested resource does not exist                     |
| `INVALID_REQUEST`      | 400         | The request body failed validation                        |
| `INSUFFICIENT_CREDITS` | 402         | You do not have enough credits to complete this operation |
| `AI_SERVICE_ERROR`     | 503         | The AI service is temporarily unavailable                 |
| `INTERNAL_ERROR`       | 500         | An unexpected server-side error occurred                  |

## Credits

Several API operations consume credits from your account balance. Credits are validated **before** the operation starts — if your balance is too low, the request is rejected immediately with a `402` status.

| Operation                                               | Credit cost   |
| ------------------------------------------------------- | ------------- |
| Brand analysis (`POST /api/brand-monitor/analyze`)      | 30 credits    |
| GEO assets generation (`POST /api/geo-assets/generate`) | 20 credits    |
| Blog creation (`POST /content-studio/create-blog`)      | 10–30 credits |
| AEO report (`POST /aeo-reports/generate`)               | 50 credits    |

<Tip>
  Check your credit balance in the CogNerd dashboard under **Settings → Credits**, or retrieve it programmatically via `GET /api/auth/me` which includes your active plan details.
</Tip>

## Quick example

Here is a complete round-trip: authenticate, then fetch your current user profile.

**Step 1 — log in and get a token**

```bash theme={null}
curl -X POST https://api.cognerd.in/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

```json theme={null}
{
  "token": "eyJhbGci...",
  "user": {
    "id": "usr_123",
    "email": "you@example.com"
  }
}
```

**Step 2 — use the token in subsequent requests**

```bash theme={null}
curl https://api.cognerd.in/api/auth/me \
  -H "Authorization: Bearer eyJhbGci..."
```

```json theme={null}
{
  "user": {
    "id": 42,
    "name": "Jane Smith",
    "email": "you@example.com",
    "plan": "monitor"
  }
}
```

## Endpoint groups

### Authentication

Manage accounts and session tokens.

| Method | Path                 | Description                          |
| ------ | -------------------- | ------------------------------------ |
| `POST` | `/api/auth/register` | Create a new account                 |
| `POST` | `/api/auth/login`    | Log in and receive a session token   |
| `GET`  | `/api/auth/me`       | Get the authenticated user's profile |

See the [Authentication](/api/authentication) page for full details and code examples.

### Brand Monitor

Scrape brand data and run AI-powered visibility analyses.

| Method   | Path                              | Auth     | Credits |
| -------- | --------------------------------- | -------- | ------- |
| `POST`   | `/api/brand-monitor/scrape`       | Required | —       |
| `POST`   | `/api/brand-monitor/analyze`      | Required | 30      |
| `GET`    | `/api/brand-monitor/analyses`     | Required | —       |
| `POST`   | `/api/brand-monitor/analyses`     | Required | —       |
| `GET`    | `/api/brand-monitor/analyses/:id` | Required | —       |
| `DELETE` | `/api/brand-monitor/analyses/:id` | Required | —       |

The `analyze` endpoint streams results in real time using **Server-Sent Events (SSE)**. See [Brand Monitor — Analyze](/api/brand-monitor/analyze) for details.

### GEO assets

Generate AI-ready GEO files for your website and manage reports.

| Method | Path                                      | Auth     | Credits |
| ------ | ----------------------------------------- | -------- | ------- |
| `POST` | `/api/geo-assets/generate`                | Required | 20      |
| `GET`  | `/api/geo-assets/job/:jobId/status`       | Required | —       |
| `GET`  | `/api/geo-assets/reports`                 | Required | —       |
| `GET`  | `/api/geo-assets/reports/:jobId`          | Required | —       |
| `GET`  | `/api/geo-assets/reports/:jobId/download` | Required | —       |

Generation is asynchronous: `POST /generate` returns a `jobId` immediately. Poll `GET /job/:jobId/status` to track progress, then fetch the report when complete. See [GEO Assets](/api/geo-assets/generate) for the full workflow.

### Content Studio

Create AI-optimized blog posts.

| Method | Path                          | Auth     | Credits |
| ------ | ----------------------------- | -------- | ------- |
| `POST` | `/content-studio/create-blog` | Required | 10–30   |

Credit cost depends on the requested content length. See [Content Studio — Create Blog](/api/content-studio/create-blog).

### AEO reports

Run Answer Engine Optimization audits.

| Method | Path                    | Auth     | Credits |
| ------ | ----------------------- | -------- | ------- |
| `POST` | `/aeo-reports/generate` | Required | 50      |

See [AEO Report](/api/content-studio/aeo-report).