# Authentication
Source: https://docs.suprlogs.com/api-reference/authentication

Use API keys to call the documented read endpoint from your own stack

## Overview

The **documented** authenticated route is **`GET /v1/projects`**. Use an **API key** from the dashboard so your backend or scripts can pull projects and **published** changelog entries without using the SuprLogs UI.

1. Sign in at [suprlogs.com/app](https://suprlogs.com/app) and open **Settings** → **API Keys**.
2. Create a key, give it a name, and **copy the secret once** — it is shown only at creation.
3. Send the secret on each request:
   * `Authorization: Bearer <your-api-key>`, or
   * `X-API-KEY: <your-api-key>`

## Scope model

Each key is created in a **Personal** or **Organization** context and can be limited to:

* **All projects** in that context, or
* **Selected projects** (e.g. a single project).

**`GET /v1/projects`** only returns projects the key is allowed to see. Wider product APIs (not listed in this reference) may apply the same rules.

## Lifecycle and security

* Create, rename, rotate, revoke, and delete keys in the **dashboard** — not via the documented API.
* Revoked or deleted keys are rejected immediately by **`GET /v1/projects`**.
* Never embed keys in client-side code; call the API from your server.

## See also

* [API Reference overview](/api-reference/introduction) — Base URL, response shape, and endpoint intent.
* [Settings → API Keys](https://suprlogs.com/app/settings/api-keys) — Key management.


# Get a published changelog entry
Source: https://docs.suprlogs.com/api-reference/changelog/get-a-published-changelog-entry

/openapi.json get /v1/changelog/{slug}/entries/{id}
Returns a single published changelog entry for the given project slug.



# List published changelog entries
Source: https://docs.suprlogs.com/api-reference/changelog/list-published-changelog-entries

/openapi.json get /v1/changelog/{slug}
Returns published changelog entries for a project slug.



# Health check
Source: https://docs.suprlogs.com/api-reference/health-check

/openapi.json get /health



# API Reference
Source: https://docs.suprlogs.com/api-reference/introduction

SuprLogs integration API — health check and read-only changelog data for custom UIs

## Purpose

The **documented** API is for teams that want **SuprLogs to own changelog data** (generation, storage, publishing) while **building their own sites or tools** on top of it. The reference intentionally stays small:

* **`GET /health`** — Liveness for monitors and deployments.
* **`GET /v1/projects`** — All projects you can access, each with **published** changelog entries (authenticated via API key; optional `entries_limit` query).
* **`GET /v1/changelog/{slug}`** — Public. List published entries for a project by slug (paginated with `limit` and `offset`).
* **`GET /v1/changelog/{slug}/entries/{id}`** — Public. Fetch a single published entry by ID.

Other HTTP routes may exist for the dashboard and product features; they are **not** part of this contract and can change without being listed here.

## Base URL

| Environment | Base URL                   |
| ----------- | -------------------------- |
| Production  | `https://api.suprlogs.com` |
| Local       | `http://localhost:4704`    |

## Authentication

* **API keys** (recommended for integrations): create them in **Dashboard → Settings → API Keys**, then send:
  * `Authorization: Bearer <your-api-key>`, or
  * `X-API-KEY: <your-api-key>`
* **`GET /v1/projects`** may also accept `X-Clerk-User-Id` for **personal** (user-owned) projects only; prefer API keys for anything automated.
* Missing or invalid credentials return **`401 Unauthorized`**.
* Key **creation, rotation, and scope** are done in the dashboard only — this reference does not document key-management HTTP routes.

## Response format

* Success responses are JSON.
* **`GET /v1/projects`** returns `{ "projects": [...], "meta": { ... } }` with published entries nested per project.
* **`GET /v1/changelog/{slug}`** returns `{ "project": {...}, "entries": [...], "meta": { ... } }`.
* **`GET /v1/changelog/{slug}/entries/{id}`** returns `{ "entry": {...} }`.
* Errors use JSON with an `error` string (and sometimes `details`).
* Typical codes: **`200`**, **`401`** (projects endpoint), **`404`** (changelog endpoints), **`500`**.

## Endpoints

The **Endpoints** sidebar is generated from `openapi.json` via `pnpm generate:openapi`. Only the supported integration paths above are included in that spec; the generator filters the full route annotations to match this intent.


# List your projects and published changelog entries
Source: https://docs.suprlogs.com/api-reference/projects/list-your-projects-and-published-changelog-entries

/openapi.json get /v1/projects
Returns all projects the caller can access, each with a slice of published changelog entries (newest first). Use this to sync or render changelogs in your own UI. Authenticate with an API key (Bearer or X-API-KEY). Optional `X-Clerk-User-Id` lists personal (user-owned) projects only — API keys are recommended for integrations.



# Introduction
Source: https://docs.suprlogs.com/index

SuprLogs — changelog data you can treat as source of truth for your own UI

## What is SuprLogs?

SuprLogs turns your GitHub commit history into human-readable changelogs. Connect repositories in the dashboard; we scan commits and store **published** changelog entries you can show on our hosted pages or **consume from your own stack**.

This documentation site focuses on the **small, stable integration surface**: a health check, an authenticated projects endpoint, and **public changelog routes** for listing or fetching individual posts by slug—ideal if you want SuprLogs as the **system of record** and a **custom frontend** elsewhere.

<Card title="Open the dashboard" icon="dashboard" href="https://suprlogs.com/app">
  Connect repos, manage projects, API keys, and hosted changelog settings.
</Card>

## What you can do with the documented API

* **`GET /health`** — Check that the API is up.
* **`GET /v1/projects`** — List every project you can access (per API key scope) with nested **published** entries. Authenticated.
* **`GET /v1/changelog/{slug}`** — List published entries for a project. Public, paginated.
* **`GET /v1/changelog/{slug}/entries/{id}`** — Fetch a single published entry. Public.

Create API keys under **Settings → API Keys** and send `Authorization: Bearer <key>` or `X-API-KEY: <key>` for authenticated routes. The changelog routes require no auth.

The base URL is **[https://api.suprlogs.com](https://api.suprlogs.com)** (or your deployment).

<Card title="API Reference" icon="terminal" href="/api-reference/introduction">
  Base URL, authentication, and OpenAPI-backed endpoints.
</Card>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Connect a repo and fetch changelog entries.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Endpoints, request/response shapes, and examples.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.suprlogs.com/quickstart

Verify the API and pull projects with published changelog entries

## Prerequisites

* A SuprLogs account ([suprlogs.com](https://suprlogs.com)) with at least one project and some **published** changelog data (use the dashboard to connect GitHub and publish).
* An **API key** from **Settings → API Keys** (scoped to the projects you want to read).

## Base URL and authentication

* **Base URL:** `https://api.suprlogs.com` (local dev: `http://localhost:4704`).
* **Authentication (for `GET /v1/projects`):** `Authorization: Bearer <your-api-key>` or `X-API-KEY: <your-api-key>`.

## Step 1: Health check

`GET /health` confirms the API is running (no auth).

```bash theme={null}
curl "https://api.suprlogs.com/health"
```

Example response (`200`):

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-03-05T12:00:00.000Z",
  "service": "suprlogs-api",
  "nodeEnv": "production"
}
```

## Step 2: List published changelog entries (public)

`GET /v1/changelog/{slug}` returns published entries for a project — no auth needed.

```bash theme={null}
curl -s "https://api.suprlogs.com/v1/changelog/my-app?limit=10"
```

The response includes `project` metadata, an `entries` array of `ChangelogEntry` objects (title, content, generated\_json, version\_label, etc.), and `meta` with pagination info.

## Step 3: Get a single entry (public)

`GET /v1/changelog/{slug}/entries/{id}` returns one published entry by UUID.

```bash theme={null}
curl -s "https://api.suprlogs.com/v1/changelog/my-app/entries/ENTRY_UUID"
```

## Step 4: Fetch all projects with entries (authenticated)

`GET /v1/projects` returns every project the API key can access, each with up to `entries_limit` published entries (default **50**, max **200**), newest first.

```bash theme={null}
curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.suprlogs.com/v1/projects?entries_limit=100"
```

Use the JSON to map `projects[].slug` to your routing and render `projects[].changelog_entries` in your own design.

## Next steps

* [API Reference](/api-reference/introduction) — Contract, auth notes, and how the spec is generated.
* [Dashboard](https://suprlogs.com/app) — Repos, publishing, and API keys.