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

# API Overview

> Shipstar V1 API reference

## Base URL

All V1 API endpoints are served at:

```
https://app.shipstar.ai/api/v1
```

## Authentication

Most public content endpoints (changelogs, blogs, KB articles) do **not** require authentication. The `/me` and mailing list endpoints require a Bearer token.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

See the [Authentication Guide](/guides/authentication) for details on creating and managing API keys.

## Endpoints

### Public Content (No Auth Required)

These endpoints serve published content and are freely accessible:

<CardGroup cols={2}>
  <Card title="Changelogs" icon="list-check" href="/api-reference/changelog/list-changelogs">
    List and retrieve published changelogs with RSS feeds
  </Card>

  <Card title="Blog Posts" icon="pen-nib" href="/api-reference/blog/list-blog-posts">
    List and retrieve published blog posts with RSS feeds
  </Card>

  <Card title="Knowledge Base" icon="book" href="/api-reference/kb/list-kb-articles">
    List and retrieve published KB article sets
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="/api-reference/health">
    Check API availability
  </Card>
</CardGroup>

### Authenticated

<CardGroup cols={2}>
  <Card title="Get Current User" icon="user" href="/api-reference/authentication">
    Verify your API token and retrieve your user profile
  </Card>

  <Card title="Mailing Lists" icon="envelope" href="/api-reference/mailing-lists/list-mailing-lists">
    List mailing lists and bulk-add recipients
  </Card>
</CardGroup>

## Response Format

All endpoints return JSON responses. Public content endpoints return the generated content directly. Error responses follow this format:

```json theme={null}
{
  "detail": "Error message describing the issue"
}
```

### Validation Errors (422)

Validation errors include location and message details:

```json theme={null}
{
  "detail": [
    {
      "loc": ["path", "public_slug"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## RSS Feeds

Published changelogs and blog posts include RSS 2.0 feeds. Append `/feed` to any changelog or blog post URL:

* `GET /changelog/{slug}/feed` — RSS feed for a single changelog
* `GET /blog/{slug}/feed` — RSS feed for a single blog post
* `GET /blogs/feed` — RSS feed of all published blog posts

## Rate Limits

| Endpoint Category           | Limit               |
| --------------------------- | ------------------- |
| Public content              | 100 requests/minute |
| Authenticated endpoints     | 100 requests/minute |
| Add mailing list recipients | 30 requests/minute  |

See the [Error Handling Guide](/guides/error-handling) for details on handling rate limit responses.