# NewsletterFIT API (v1.0.0)

> Generated from the OpenAPI 3.1 spec: https://newsletterfit.com/api/v1/openapi.yaml · interactive reference: https://newsletterfit.com/docs/api · MCP server: https://newsletterfit.com/docs/mcp.md

Customer REST API for newsletter intelligence: search publications and articles,
inspect sponsors and entities, and (on Enterprise) export a 14-day graph snapshot.

Authenticate with `Authorization: Bearer nf_live_…` or `nf_test_…`. The REST API takes
API keys only; OAuth 2.1 sign-in is for the MCP server (https://newsletterfit.com/docs/mcp).
Effective permission is scope ∩ plan entitlement (`apiAccess`).

Typed ids in MCP responses use prefixes (`nl_`, `is_`, `sp_`, `tp_`, `en_`).
REST path params still accept numeric ids; MCP tool args accept either form.
MCP tool input schemas live at `/api/v1/mcp-tools.json` (same registry as `tools/list`).
MCP setup and tool reference: https://newsletterfit.com/docs/mcp

## Limits
Monthly meters per account, shared by REST and MCP and reset on the 1st (UTC):
Pro 500 searches / 2,500 profile views; Intelligence and Enterprise 2,000 / 10,000;
Enterprise also 200 exports. Rate limit: 90 requests a minute per key, reported in
`RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers.

## Errors
Every error uses the envelope `{ success: false, error: { code, message, details } }`.
- 401 `AUTH_ERROR`: missing or invalid key, or the key lacks the operation's scope
  (`details.required` names it).
- 402: the plan lacks API access or the feature, or the monthly meter is used up.
- 404: unknown id or slug.
- 429: rate limit; wait `RateLimit-Reset` seconds.

## Base URL

- `https://newsletterfit.com/api/v1` (Production)

## Pagination

List endpoints take `page` (1-based) and `limit` (1–100, default 20) and return `meta.page`, `meta.limit` and, where known, `meta.total`. Ask for the next page while `page * limit < total`.

## Endpoints

### Search

#### `GET /search`

**Search newsletters, articles, and mentions** · scope `search:read`

Requires scope `search:read`. Counts against the API search meter.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | yes | Search text, e.g. a topic, company or newsletter name |
| `page` | query | integer; default 1 | no | 1-based page number |
| `limit` | query | integer; 1–100; default 20 | no | Results per page |
| `momentumWindow` | query | string; one of 7d, 30d, 90d | no | Window for the momentum signal on newsletter results |

```bash
curl "https://newsletterfit.com/api/v1/search?q=ai%20agents" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Ranked search results |
| 401 | Missing or invalid API key / scope |
| 402 | Plan entitlement or usage meter exceeded |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

Example response:

```json
{
  "success": true,
  "data": {
    "query": "ai agents",
    "newsletters": [
      {
        "id": 42,
        "self": "/api/v1/publications/42",
        "name": "Example Newsletter",
        "audience": {
          "value": 12000,
          "label": "12K",
          "basis": "substack"
        }
      }
    ]
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "request_id": "req_example"
  }
}
```

### Newsletters

#### `GET /publications`

**List active publications** · scope `publications:read`

Requires scope `publications:read`. Counts against the API search meter.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer; default 1 | no | 1-based page number |
| `limit` | query | integer; 1–100; default 20 | no | Results per page |
| `q` | query | string | no | Name or topic search |
| `host` | query | string | no | Exact publication host / subdomain lookup |
| `sort` | query | string; one of recent | no |  |
| `momentumWindow` | query | string; one of 7d, 30d, 90d | no | Window for the momentum signal on newsletter results |

```bash
curl "https://newsletterfit.com/api/v1/publications" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Publication cards |
| 401 | Missing or invalid API key / scope |
| 402 | Plan entitlement or usage meter exceeded |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

#### `GET /publications/by/{slug}`

**Publication profile by slug** · scope `publications:read`

Requires scope `publications:read`. Counts as an API profile view.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `slug` | path | string | yes |  |
| `momentumWindow` | query | string; one of 7d, 30d, 90d | no | Window for the momentum signal on newsletter results |

```bash
curl "https://newsletterfit.com/api/v1/publications/by/EXAMPLE_SLUG" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Publication profile |
| 401 | Missing or invalid API key / scope |
| 404 | Resource not found |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

#### `GET /publications/{id}`

**Publication profile by id** · scope `publications:read`

Requires scope `publications:read`. Counts as an API profile view.
Path accepts a numeric id. MCP tools return the same resource as `nl_{id}`.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes |  |
| `momentumWindow` | query | string; one of 7d, 30d, 90d | no | Window for the momentum signal on newsletter results |

```bash
curl "https://newsletterfit.com/api/v1/publications/EXAMPLE_ID" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Publication profile |
| 401 | Missing or invalid API key / scope |
| 404 | Resource not found |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

#### `GET /publications/{id}/intel-summary`

**Compact intel summary for a publication** · scope `publications:read`

Requires scope `publications:read`.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes |  |

```bash
curl "https://newsletterfit.com/api/v1/publications/EXAMPLE_ID/intel-summary" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Intel summary |
| 401 | Missing or invalid API key / scope |
| 404 | Resource not found |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

### Articles

#### `GET /articles`

**List articles** · scope `publications:read`

Requires scope `publications:read`. Optional `publicationId` filter.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer; default 1 | no | 1-based page number |
| `limit` | query | integer; 1–100; default 20 | no | Results per page |
| `publicationId` | query | integer | no |  |

```bash
curl "https://newsletterfit.com/api/v1/articles" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Article list |
| 401 | Missing or invalid API key / scope |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

#### `GET /articles/{id}`

**Article by id** · scope `publications:read`

Requires scope `publications:read`. Public fields only (no plainText).
Path accepts a numeric id. MCP tools return the same resource as `is_{id}`.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes |  |

```bash
curl "https://newsletterfit.com/api/v1/articles/EXAMPLE_ID" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Article |
| 401 | Missing or invalid API key / scope |
| 404 | Resource not found |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

### Entities

#### `GET /entities/{type}`

**Search entities by type** · scope `entities:read`

Requires scope `entities:read`. Type is one of company, product, person,
technology, topic, guest, brand, sponsor. Guest and person stay separate.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | path | string; one of company, product, person, technology, topic, guest, brand, sponsor | yes |  |
| `q` | query | string | yes |  |
| `page` | query | integer; default 1 | no | 1-based page number |
| `limit` | query | integer; 1–100; default 20 | no | Results per page |

```bash
curl "https://newsletterfit.com/api/v1/entities/company?q=ai%20agents" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Entity list |
| 401 | Missing or invalid API key / scope |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

#### `GET /entities/{type}/{id}`

**Entity page by type and id** · scope `entities:read`

Requires scope `entities:read`. Guest ≠ person.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | path | string | yes |  |
| `id` | path | string | yes |  |

```bash
curl "https://newsletterfit.com/api/v1/entities/company/EXAMPLE_ID" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Entity |
| 401 | Missing or invalid API key / scope |
| 404 | Resource not found |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

### Exports

#### `POST /exports`

**14-day graph export snapshot** · scope `exports:write`

Requires plan entitlement `exports` (Enterprise). Counts as one export.
Returns publications, articles, entities, and links for the last 14 days.
Article text and raw files are not included.

```bash
curl -X POST "https://newsletterfit.com/api/v1/exports" \
  -H "Authorization: Bearer nf_live_YOUR_KEY"
```

| Status | Meaning |
| --- | --- |
| 200 | Snapshot accepted |
| 401 | Missing or invalid API key / scope |
| 402 | Plan entitlement or usage meter exceeded |
| 429 | Too many requests for this key (90 a minute). Retry after RateLimit-Reset seconds. |

Support: support@newsletterfit.com