Release Notes API Reference

The Releases API lets you generate, edit, and distribute release notes. You point Swisstools at one or more GitHub repository URLs and a date range, and the AI generates a structured changelog from the commit history. From there you can refine the draft, publish it, export it as Markdown, and send it to a Slack channel or email list. All release endpoints require session authentication. See Authentication for details. Release status values: processing (AI generation in progress), draft (ready for editing), published (finalized and visible).

List Releases

GET /api/projects/:projectId/releases Returns all releases for the specified project, ordered by creation date descending. Path Parameters

string

required

The UUID of the project.

Request

curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases \
  -b cookies.txt

Response

[
  {
    "id": "018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c",
    "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
    "title": "Release v1.2.0",
    "content": "## What's New\n\n- Improved checkout flow\n- Fixed payment retry bug",
    "status": "published",
    "fromDate": "2024-01-01T00:00:00.000Z",
    "toDate": "2024-01-31T00:00:00.000Z",
    "repoUrls": ["https://github.com/acme/payments"],
    "commitCount": 24,
    "errorMessage": null,
    "publishedAt": "2024-02-01T09:00:00.000Z",
    "createdAt": "2024-01-31T20:00:00.000Z",
    "updatedAt": "2024-02-01T09:00:00.000Z"
  }
]

Generate Release

POST /api/projects/:projectId/releases/generate Triggers AI generation of release notes from GitHub commits in the given date range. The release is created immediately with status: "processing" and transitions to status: "draft" when the AI finishes (or status: "draft" with an errorMessage if generation fails). Poll the Get Release endpoint to check progress. Path Parameters

string

required

The UUID of the project.

Request Body

string

required

Start of the commit date range, ISO 8601 format (e.g., 2024-01-01).

string

required

End of the commit date range, ISO 8601 format (e.g., 2024-01-31).

array

required

One or more GitHub repository URLs to pull commits from (e.g., ["https://github.com/org/repo"]).

Request

curl -X POST https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/generate \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "fromDate": "2024-01-01",
    "toDate": "2024-01-31",
    "repoUrls": ["https://github.com/acme/payments"]
  }'

Response — 201 Created

{
  "id": "018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "title": "Release — Jan 1 to Jan 31",
  "content": "",
  "status": "processing",
  "fromDate": "2024-01-01T00:00:00.000Z",
  "toDate": "2024-01-31T00:00:00.000Z",
  "repoUrls": ["https://github.com/acme/payments"],
  "commitCount": 0,
  "errorMessage": null,
  "publishedAt": null,
  "createdAt": "2024-01-31T20:00:00.000Z",
  "updatedAt": "2024-01-31T20:00:00.000Z"
}

Get Release

GET /api/projects/:projectId/releases/:releaseId Returns a single release by its ID. Use this to poll for status transitions from processing to draft. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release.

Request

curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c \
  -b cookies.txt

Response

{
  "id": "018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "title": "Release v1.2.0",
  "content": "## What's New\n\n- Improved checkout flow\n- Fixed payment retry bug",
  "status": "draft",
  "fromDate": "2024-01-01T00:00:00.000Z",
  "toDate": "2024-01-31T00:00:00.000Z",
  "repoUrls": ["https://github.com/acme/payments"],
  "commitCount": 24,
  "errorMessage": null,
  "publishedAt": null,
  "createdAt": "2024-01-31T20:00:00.000Z",
  "updatedAt": "2024-01-31T20:05:00.000Z"
}

Update Release

PUT /api/projects/:projectId/releases/:releaseId Updates the title or content of a release. You can edit draft releases before publishing. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release to update.

Request Body

string

Updated release title.

string

Updated Markdown content.

Request

curl -X PUT https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Release v1.2.0",
    "content": "## What'\''s New\n\n- Improved checkout flow\n- Fixed payment retry bug\n- Added Apple Pay support"
  }'

Response

{
  "id": "018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "title": "Release v1.2.0",
  "content": "## What's New\n\n- Improved checkout flow\n- Fixed payment retry bug\n- Added Apple Pay support",
  "status": "draft",
  "fromDate": "2024-01-01T00:00:00.000Z",
  "toDate": "2024-01-31T00:00:00.000Z",
  "repoUrls": ["https://github.com/acme/payments"],
  "commitCount": 24,
  "errorMessage": null,
  "publishedAt": null,
  "createdAt": "2024-01-31T20:00:00.000Z",
  "updatedAt": "2024-02-01T08:30:00.000Z"
}

Delete Release

DELETE /api/projects/:projectId/releases/:releaseId Permanently deletes a release and all its attachments. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release to delete.

Request

curl -X DELETE https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c \
  -b cookies.txt

Response

{"success": true}

Publish Release

POST /api/projects/:projectId/releases/:releaseId/publish Marks a draft release as published and records the current timestamp in publishedAt. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release to publish.

Request

curl -X POST https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c/publish \
  -b cookies.txt

Response

{
  "id": "018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "title": "Release v1.2.0",
  "content": "## What's New\n\n- Improved checkout flow\n- Fixed payment retry bug",
  "status": "published",
  "fromDate": "2024-01-01T00:00:00.000Z",
  "toDate": "2024-01-31T00:00:00.000Z",
  "repoUrls": ["https://github.com/acme/payments"],
  "commitCount": 24,
  "errorMessage": null,
  "publishedAt": "2024-02-01T09:00:00.000Z",
  "createdAt": "2024-01-31T20:00:00.000Z",
  "updatedAt": "2024-02-01T09:00:00.000Z"
}

Export Release

GET /api/projects/:projectId/releases/:releaseId/export Returns the release content as a downloadable Markdown file. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release to export.

Request

curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c/export \
  -b cookies.txt \
  -o release-v1.2.0.md

Response — 200 OK with Content-Type: text/markdown and a Content-Disposition: attachment header containing the Markdown content.

Send to Slack

POST /api/projects/:projectId/releases/:releaseId/send-slack Sends the release to the Slack channel configured in the project’s release settings. Requires a Slack integration to be set up for the project. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release to send.

Request

curl -X POST https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c/send-slack \
  -b cookies.txt

Response

{"success": true}

Send via Email

POST /api/projects/:projectId/releases/:releaseId/send-email Sends the release to the email recipients configured in the project’s release settings. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the release to send.

Request

curl -X POST https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/releases/018eb19c-8d0e-4f5a-b6c7-9d0e1f2a3b4c/send-email \
  -b cookies.txt

Response

{"success": true}

Release Object

string

UUID that uniquely identifies the release.

string

UUID of the project that owns this release.

string

The release title, editable after generation.

string

The release body in Markdown format. Empty string while status is processing.

string

Current lifecycle state. One of processing, draft, or published.

string

ISO 8601 timestamp for the start of the commit range used to generate this release.

string

ISO 8601 timestamp for the end of the commit range.

array

Array of GitHub repository URLs that were analyzed.

integer

Number of commits included in the generated release notes.

string

Populated if AI generation failed; null otherwise.

string

ISO 8601 timestamp of when the release was published, or null if still a draft.

string

ISO 8601 timestamp of creation.

string

ISO 8601 timestamp of the last update.

Overview

Endpoints

Release Notes API Reference

List Releases

Generate Release

Get Release

Update Release

Delete Release

Publish Release

Export Release

Send to Slack

Send via Email

Release Object

​List Releases

​Generate Release

​Get Release

​Update Release

​Delete Release

​Publish Release

​Export Release

​Send to Slack

​Send via Email

​Release Object

List Releases

Generate Release

Get Release

Update Release

Delete Release

Publish Release

Export Release

Send to Slack

Send via Email

Release Object