API Documentation

Introduction

The WhatShipped API lets you generate and retrieve release notes from any connected GitHub, GitLab, or Bitbucket repository. All endpoints live under:

https://api.whatshipped.dev/api/v1

API versioning is path-based (/api/v1). Breaking changes will be introduced under a new version path.

Authentication

Every request must include an API key as a Bearer token in the Authorization header. Create an API key →

Authorization: Bearer sl_abcdef1234567890

List release notes for the authenticated user. No credits consumed.

Query Parameters

Response — 200

Array of release note summary objects.

Fetch a single release note by ID. No credits consumed.

Path Parameters

Response — 200

Error Shapes

Generate release notes for a commit range. Consumes 1 credit (2 if includeDiffs is true).

Request Headers

Request Body

Response — 200

Error Shapes

Credits

Each API call to the generate endpoint deducts credits from your balance. View your balance →

Error Reference

All errors return JSON with an error field.

{
  "error": "Insufficient credits"
}

Code Examples

Generate release notes for a commit range.

#!/usr/bin/env bash

curl -X POST https://api.whatshipped.dev/api/v1/release-notes/generate \
  -H "Authorization: Bearer sl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "repoFullName": "acme/backend",
    "fromRef": "v2.2.0",
    "toRef": "v2.3.0",
    "versionTag": "v2.3.0",
    "tone": "professional"
  }'

const response = await fetch(
  'https://api.whatshipped.dev/api/v1/release-notes/generate',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sl_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider: 'github',
      repoFullName: 'acme/backend',
      fromRef: 'v2.2.0',
      toRef: 'v2.3.0',
      versionTag: 'v2.3.0',
      tone: 'professional',
    }),
  }
);

const data = await response.json();
console.log(data.content); // Markdown release notes

import requests

response = requests.post(
    "https://api.whatshipped.dev/api/v1/release-notes/generate",
    headers={
        "Authorization": "Bearer sl_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "provider": "github",
        "repoFullName": "acme/backend",
        "fromRef": "v2.2.0",
        "toRef": "v2.3.0",
        "versionTag": "v2.3.0",
        "tone": "professional",
    },
)

data = response.json()
print(data["content"])  # Markdown release notes