# Niobe API & MCP

Niobe listens across the public web and surfaces, for a business, the people **talking about them**
(feedback) and the people **looking for what they do** (discovery / new customers), clustered into
"signals" with a ready-to-send draft reply.

## Authentication
All requests use a Bearer token (a personal access token). Create and manage tokens at
`https://niobe.live/settings/api-tokens`. Tokens are **read-only** or **read & write**.

```
Authorization: Bearer <your-token>
Accept: application/json
```

Base URL: `https://niobe.live/api/v1`
Rate limit: 60 requests/minute per token.

## Concepts
- **Project** — one thing Niobe monitors (a business, product, or topic). Two pillars:
  `track_feedback` and `track_discovery`.
- **Discovery** — one public post Niobe surfaced. `pillar` is `feedback` or `discovery`;
  `category`, `intent_score`, `relevance_score`, `status`, an `action_draft`, and a `source` link.
- **Signal** — a cluster of discoveries under a shared theme.

## Endpoints

### GET /me
The authenticated identity and plan.

### GET /projects
List your projects. Query: `per_page` (max 100).

### POST /projects  *(write)*
Create a project. Body: `name` (required), `url`, `description`, `target_audience`,
`problems_solved`, `competitors[]`, `track_feedback`, `track_discovery`. Honors your plan limit.

### GET /projects/{id}
A single project.

### PATCH /projects/{id}  *(write)*
Update a project (same fields as create).

### DELETE /projects/{id}  *(write)*
Archive a project.

### POST /projects/{id}/scan  *(write, requires subscription)*
Queue an immediate monitoring pass. Returns 202.

### GET /projects/{id}/signals
The clustered overview per pillar: `{ feedback, discovery }`, each with `total`, `clusters[]`
(`theme`, `count`, `representative`) and `other_count`.

### GET /projects/{id}/discoveries
The individual posts. Query: `pillar` (feedback|discovery), `category`, `status`, `theme`,
`q`, `sort` (recent|intent), `per_page` (max 100).

### GET /discoveries/{id}
A single discovery.

### PATCH /discoveries/{id}  *(write)*
Record an outcome. Body: `action` — one of `save`, `dismiss`, `useful`, `irrelevant`,
`contacted`, `replied`, `converted`, `responded`, `resolved`.

## Example

```bash
curl -s https://niobe.live/api/v1/projects \
  -H "Authorization: Bearer $NIOBE_TOKEN" \
  -H "Accept: application/json"
```

## MCP server
Niobe is also an MCP server so agents (Claude and others) can use it directly.

- Endpoint (streamable HTTP): `https://niobe.live/mcp`
- Auth: the same Bearer token (`Authorization: Bearer <token>`).
- Tools: `list_projects`, `get_project`, `list_signals`, `list_discoveries`, `get_discovery`,
  `update_discovery_status` *(write)*, `create_project` *(write)*, `trigger_scan` *(write)*.

Example client config:

```json
{
  "mcpServers": {
    "niobe": {
      "type": "http",
      "url": "https://niobe.live/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}
```

OpenAPI spec: `https://niobe.live/api/v1/../openapi.yaml`