REST API Reference

The ShipPulse REST API lets you manage testimonials, changelog entries, monitors, incidents, and more programmatically. Available on Pro and Agency plans.

Introduction

The ShipPulse API is a RESTful API that uses JSON for request and response bodies. All endpoints are prefixed with /api/v1.

Base URL: https://shippulse.dev

Authentication

Authenticate using an API key in the Authorization header as a Bearer token. Create API keys in your project Settings → API Keys.

bash

curl https://shippulse.dev/api/v1/testimonials \
  -H "Authorization: Bearer sp_your_api_key_here"

API keys start with sp_ and are scoped to a single project. Never expose your API key in client-side code.

Testimonials

GET

/api/v1/testimonials

List testimonials. Query params: status, page, limit.

GET

/api/v1/testimonials/:id

Get a single testimonial.

POST

/api/v1/testimonials

Create a testimonial.

PATCH

/api/v1/testimonials/:id

Update status, featured, author fields.

DELETE

/api/v1/testimonials/:id

Delete a testimonial.

Changelog

GET

/api/v1/changelog

List changelog entries. Query params: published, page, limit.

GET

/api/v1/changelog/:id

Get a single entry.

POST

/api/v1/changelog

Create an entry.

PATCH

/api/v1/changelog/:id

Update title, body, published status, etc.

DELETE

/api/v1/changelog/:id

Delete an entry.

Monitors

GET

/api/v1/monitors

List uptime monitors.

GET

/api/v1/monitors/:id

Get a single monitor.

POST

/api/v1/monitors

Create a monitor.

PATCH

/api/v1/monitors/:id

Update monitor settings.

DELETE

/api/v1/monitors/:id

Delete a monitor.

Incidents

GET

/api/v1/incidents

List incidents. Query param: resolved=true|false.

POST

/api/v1/incidents

Create an incident.

POST

/api/v1/incidents/:id/updates

Add an update to an incident.

Subscribers

GET

/api/v1/subscribers

List active subscribers. Query params: page, limit.

Widgets

GET

/api/v1/widgets

List testimonial widgets.

Rate Limits

API endpoints are rate-limited per API key. When exceeded, the API returns 429 Too Many Requests. See Rate Limiting guide for full details.

Endpoint group	Limit	Window
/api/v1/*	100 requests	1 minute
/api/collect	20 requests	10 minutes
/api/subscribe	5 requests	15 minutes

Error Codes

See the Error Handling guide for the full error schema and retry recommendations.

Code	Meaning
400	Bad Request — invalid input body
401	Unauthorized — missing or invalid API key
403	Forbidden — plan does not include API access
404	Not Found — resource does not exist
422	Unprocessable Entity — validation failed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Examples

List approved testimonials

bash

curl "https://shippulse.dev/api/v1/testimonials?status=approved&page=1&limit=20" \
  -H "Authorization: Bearer sp_your_api_key"

Create a changelog entry

javascript

const res = await fetch("https://shippulse.dev/api/v1/changelog", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "New feature: Dark mode",
    body: "We've added dark mode support across all pages.",
    body_format: "markdown",
    type: "feature",
    published: true,
  }),
});
const { data } = await res.json();

Create and resolve an incident

bash

# Create
curl -X POST "https://shippulse.dev/api/v1/incidents" \
  -H "Authorization: Bearer sp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"API latency degradation","impact":"major","body":"Investigating."}'

# Resolve
curl -X POST "https://shippulse.dev/api/v1/incidents/INCIDENT_ID/updates" \
  -H "Authorization: Bearer sp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved","body":"The issue has been resolved."}'

CI/CD Integration

Publish changelog entries automatically from your CI/CD pipeline. Add your API key as a secret in your CI/CD provider.

GitHub Actions

yaml

name: Publish changelog
on:
  release:
    types: [published]
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Publish to ShipPulse
        run: |
          curl -s -X POST "https://shippulse.dev/api/v1/changelog" \
            -H "Authorization: Bearer ${{ secrets.SHIPPULSE_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "title": "${{ github.event.release.name }}",
              "body": "${{ github.event.release.body }}",
              "type": "feature",
              "published": true,
              "notify_subscribers": true
            }'

GitLab CI

yaml

publish_changelog:
  stage: deploy
  only: [tags]
  script:
    - |
      curl -s -X POST "https://shippulse.dev/api/v1/changelog" \
        -H "Authorization: Bearer $SHIPPULSE_API_KEY" \
        -H "Content-Type: application/json" \
            -d '{"title":"$CI_COMMIT_TAG","type":"feature","published":true}'

Interactive playground

REST API Reference

The ShipPulse REST API lets you manage testimonials, changelog entries, monitors, incidents, and more programmatically. Available on Pro and Agency plans.

Introduction

The ShipPulse API is a RESTful API that uses JSON for request and response bodies. All endpoints are prefixed with /api/v1.

Base URL: https://shippulse.dev

Authentication

Authenticate using an API key in the Authorization header as a Bearer token. Create API keys in your project Settings → API Keys.

bash

curl https://shippulse.dev/api/v1/testimonials \
  -H "Authorization: Bearer sp_your_api_key_here"

API keys start with sp_ and are scoped to a single project. Never expose your API key in client-side code.

Testimonials

GET

/api/v1/testimonials

List testimonials. Query params: status, page, limit.

GET

/api/v1/testimonials/:id

Get a single testimonial.

POST

/api/v1/testimonials

Create a testimonial.

PATCH

/api/v1/testimonials/:id

Update status, featured, author fields.

DELETE

/api/v1/testimonials/:id

Delete a testimonial.

Changelog

GET

/api/v1/changelog

List changelog entries. Query params: published, page, limit.

GET

/api/v1/changelog/:id

Get a single entry.

POST

/api/v1/changelog

Create an entry.

PATCH

/api/v1/changelog/:id

Update title, body, published status, etc.

DELETE

/api/v1/changelog/:id

Delete an entry.

Monitors

GET

/api/v1/monitors

List uptime monitors.

GET

/api/v1/monitors/:id

Get a single monitor.

POST

/api/v1/monitors

Create a monitor.

PATCH

/api/v1/monitors/:id

Update monitor settings.

DELETE

/api/v1/monitors/:id

Delete a monitor.

Incidents

GET

/api/v1/incidents

List incidents. Query param: resolved=true|false.

POST

/api/v1/incidents

Create an incident.

POST

/api/v1/incidents/:id/updates

Add an update to an incident.

Subscribers

GET

/api/v1/subscribers

List active subscribers. Query params: page, limit.

Widgets

GET

/api/v1/widgets

List testimonial widgets.

Rate Limits

API endpoints are rate-limited per API key. When exceeded, the API returns 429 Too Many Requests. See Rate Limiting guide for full details.

Endpoint group	Limit	Window
/api/v1/*	100 requests	1 minute
/api/collect	20 requests	10 minutes
/api/subscribe	5 requests	15 minutes

Error Codes

See the Error Handling guide for the full error schema and retry recommendations.

Code	Meaning
400	Bad Request — invalid input body
401	Unauthorized — missing or invalid API key
403	Forbidden — plan does not include API access
404	Not Found — resource does not exist
422	Unprocessable Entity — validation failed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Examples

List approved testimonials

bash

curl "https://shippulse.dev/api/v1/testimonials?status=approved&page=1&limit=20" \
  -H "Authorization: Bearer sp_your_api_key"

Create a changelog entry

javascript

const res = await fetch("https://shippulse.dev/api/v1/changelog", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "New feature: Dark mode",
    body: "We've added dark mode support across all pages.",
    body_format: "markdown",
    type: "feature",
    published: true,
  }),
});
const { data } = await res.json();

Create and resolve an incident

bash

# Create
curl -X POST "https://shippulse.dev/api/v1/incidents" \
  -H "Authorization: Bearer sp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"API latency degradation","impact":"major","body":"Investigating."}'

# Resolve
curl -X POST "https://shippulse.dev/api/v1/incidents/INCIDENT_ID/updates" \
  -H "Authorization: Bearer sp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved","body":"The issue has been resolved."}'

CI/CD Integration

Publish changelog entries automatically from your CI/CD pipeline. Add your API key as a secret in your CI/CD provider.

GitHub Actions

yaml

name: Publish changelog
on:
  release:
    types: [published]
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - name: Publish to ShipPulse
        run: |
          curl -s -X POST "https://shippulse.dev/api/v1/changelog" \
            -H "Authorization: Bearer ${{ secrets.SHIPPULSE_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "title": "${{ github.event.release.name }}",
              "body": "${{ github.event.release.body }}",
              "type": "feature",
              "published": true,
              "notify_subscribers": true
            }'

GitLab CI

yaml

publish_changelog:
  stage: deploy
  only: [tags]
  script:
    - |
      curl -s -X POST "https://shippulse.dev/api/v1/changelog" \
        -H "Authorization: Bearer $SHIPPULSE_API_KEY" \
        -H "Content-Type: application/json" \
            -d '{"title":"$CI_COMMIT_TAG","type":"feature","published":true}'