API reference

List projects

Scope: read

The projects this key can use. A quick way to find the slug.

curl "https://shipnoted.com/api/v1/projects" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Projects.

{
  "ok": true,
  "projects": [
    {
      "slug": "acme",
      "name": "Acme",
      "url": "https://acme.shipnoted.com",
      "live": true
    }
  ]
}

Get the project

Scope: read

Names, addresses and counts. The first call a new tool makes, to check its key and slug.

curl "https://shipnoted.com/api/v1/your-slug/project" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Project.

Requests grouped into themes

Scope: read

The same wish in different words, grouped, ranked by revenue then votes.

curl "https://shipnoted.com/api/v1/your-slug/themes" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Themes.

Customer groups that have voted

Scope: read

The values ?segment= accepts, with votes and revenue.

curl "https://shipnoted.com/api/v1/your-slug/segments" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Segments.

The loop in numbers

Scope: read

Requests received and shipped, median days to ship, people told, and pull requests waiting for you.

curl "https://shipnoted.com/api/v1/your-slug/loop" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Stats and suggestions.

List releases

Scope: read

curl "https://shipnoted.com/api/v1/your-slug/releases" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Releases, newest first, with hasMore.

Create a release

Scope: releases:write

Add publish: true to publish at once (and email: true to email confirmed subscribers). Without it you get a draft.

curl -X POST "https://shipnoted.com/api/v1/your-slug/releases" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"Dark mode","body":"- Dark mode for the dashboard","version":"v1.4.0","tags":["new"],"publish":true,"email":true}'

Returns 201: The release.

{
  "ok": true,
  "release": {
    "id": "r_abc",
    "title": "Dark mode",
    "status": "published",
    "url": "https://acme.shipnoted.com/p/acme/dark-mode"
  },
  "emailed": 212
}

Get a release

Scope: read

Includes the requests it answers.

curl "https://shipnoted.com/api/v1/your-slug/releases/r_abc" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: The release with linked requests.

Update a release

Scope: releases:write

Any of the create fields. A published release changes in place.

curl -X PATCH "https://shipnoted.com/api/v1/your-slug/releases/r_abc" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: The release.

Delete a release

Scope: releases:write

curl -X DELETE "https://shipnoted.com/api/v1/your-slug/releases/r_abc" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: ok.

Publish a draft

Scope: releases:write

Linked requests become Shipped and the people who voted for them are emailed, exactly as from the dashboard.

curl -X POST "https://shipnoted.com/api/v1/your-slug/releases/r_abc/publish" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: The public url and how many were told.

{
  "ok": true,
  "url": "https://acme.shipnoted.com/p/acme/dark-mode",
  "emailed": 212,
  "votersNotified": 14,
  "requestsShipped": 3
}

Draft release notes from changes

Scope: releases:write

Send pull request titles or commit subjects; Claude (or the built-in writer) groups them into New, Improved and Fixed. The draft is never published for you.

curl -X POST "https://shipnoted.com/api/v1/your-slug/draft" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY" \
  -H "content-type: application/json" \
  -d '{"version":"v1.4.0","items":[{"title":"feat: dark mode (#212)"},{"title":"fix: login loop (#215)"}]}'

Returns 201: The draft's id and who wrote it (claude or builtin).

{
  "ok": true,
  "releaseId": "r_abc",
  "source": "claude"
}

List requests

Scope: read

curl "https://shipnoted.com/api/v1/your-slug/feedback" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Requests, with total and hasMore.

File a request, or move one

Scope: feedback:write

With a title it files a new request (send idempotencyKey so a retry files it once). With an id and a status it moves an existing request.

curl -X POST "https://shipnoted.com/api/v1/your-slug/feedback" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"Export to CSV","body":"We need it for invoices","email":"ada@acme.com","source":"Support","idempotencyKey":"ticket-8841"}'

Returns 201: The new request's id and reference, or ok.

{
  "ok": true,
  "id": "f_x",
  "ref": "SN-42",
  "duplicate": false
}

Get a request

Scope: read

The id may be its reference, like SN-42. Includes comments and linked GitHub issues.

curl "https://shipnoted.com/api/v1/your-slug/feedback/SN-42" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: The request.

Change a request

Scope: feedback:write

Status and timing, who it is assigned to, and whether it is archived. An archived request leaves the inbox and the public board but keeps its votes.

curl -X PATCH "https://shipnoted.com/api/v1/your-slug/feedback/SN-42" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: The request.

Delete a request

Scope: feedback:write

curl -X DELETE "https://shipnoted.com/api/v1/your-slug/feedback/SN-42" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: ok.

Reply as the team

Scope: feedback:write

Set internal: true for a note only your team sees.

curl -X POST "https://shipnoted.com/api/v1/your-slug/feedback/SN-42/comments" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY" \
  -H "content-type: application/json" \
  -d '{"body":"…"}'

Returns 201: The comment.

List subscribers

Scope: subscribers:read

Email addresses are personal data, so this has its own scope.

curl "https://shipnoted.com/api/v1/your-slug/subscribers" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Subscribers and total.

List webhook endpoints

Scope: webhooks:write

curl "https://shipnoted.com/api/v1/your-slug/webhooks" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: Endpoints and the event catalogue.

Create a webhook endpoint

Scope: webhooks:write

Events: feedback.created, feedback.status_changed, comment.created, release.published, feedback.voted, subscriber.confirmed. All of them when events is left out. The signing secret is in this response and never shown again.

curl -X POST "https://shipnoted.com/api/v1/your-slug/webhooks" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/hooks/shipnoted","events":["feedback.created","release.published"]}'

Returns 201: The endpoint and its secret.

{
  "ok": true,
  "endpoint": {
    "id": "we_abc",
    "url": "https://example.com/hooks/shipnoted",
    "active": true
  },
  "secret": "whsec_…"
}

Pause, resume or change an endpoint

Scope: webhooks:write

curl -X PATCH "https://shipnoted.com/api/v1/your-slug/webhooks/we_abc" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: The endpoint.

Delete an endpoint

Scope: webhooks:write

curl -X DELETE "https://shipnoted.com/api/v1/your-slug/webhooks/we_abc" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: ok.

Send a test ping

Scope: webhooks:write

A signed ping event, sent now. Reports what your server answered.

curl -X POST "https://shipnoted.com/api/v1/your-slug/webhooks/we_abc/test" \
  -H "Authorization: Bearer $SHIPNOTED_API_KEY"

Returns 200: ok and a note.