API Overview

Base URL: https://cases.shipmentbot.com/api/v1

The API follows JSON:API-style envelopes with HATEOAS links and predictable pagination metadata. All protected endpoints accept X-API-Key auth and can also work with an authenticated browser session.

Quick Start

curl -X GET "https://cases.shipmentbot.com/api/v1/campaigns?page[number]=1&page[size]=2" \
  -H "Accept: application/json" \
  -H "X-API-Key: csb_live_your_token_here"

Response Envelope

Collection responses return data, included, links, and meta.page:

{
  "data": [
    {
      "id": "1",
      "type": "campaigns",
      "attributes": {
        "name": "Weekly Customer Stories",
        "cadence": "weekly",
        "deadline_day": "friday",
        "nudge_days": ["monday", "wednesday", "friday"],
        "format_template": "spin",
        "active": true,
        "created_at": "2026-03-01T10:00:00.000Z",
        "updated_at": "2026-03-01T10:00:00.000Z"
      },
      "relationships": {
        "campaign_periods": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaigns/1/relationships/campaign_periods",
            "related": "https://cases.shipmentbot.com/api/v1/campaigns/1/campaign_periods"
          },
          "data": [{ "id": "11", "type": "campaign_periods" }]
        }
      },
      "links": {
        "self": "https://cases.shipmentbot.com/api/v1/campaigns/1"
      }
    }
  ],
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns?page%5Bnumber%5D=1&page%5Bsize%5D=2",
    "first": "https://cases.shipmentbot.com/api/v1/campaigns?page%5Bnumber%5D=1&page%5Bsize%5D=2",
    "last": "https://cases.shipmentbot.com/api/v1/campaigns?page%5Bnumber%5D=3&page%5Bsize%5D=2",
    "next": "https://cases.shipmentbot.com/api/v1/campaigns?page%5Bnumber%5D=2&page%5Bsize%5D=2",
    "prev": null
  },
  "meta": {
    "page": {
      "number": 1,
      "size": 2,
      "total_records": 6,
      "total_pages": 3
    }
  }
}

Single-resource responses return the same envelope with an empty meta hash:

{
  "data": {
    "id": "4",
    "type": "employees",
    "attributes": {
      "name": "Jamie Writer",
      "email": "jamie.writer@example.com",
      "created_at": "2026-03-04T16:02:12.000Z",
      "updated_at": "2026-03-04T16:02:12.000Z"
    },
    "relationships": {
      "submissions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/employees/4/relationships/submissions",
          "related": "https://cases.shipmentbot.com/api/v1/submissions?filter%5Bemployee_id%5D=4"
        },
        "data": [{ "id": "15", "type": "submissions" }]
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/employees/4"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/employees/4"
  },
  "meta": {}
}

Error Envelope

Errors return data: null and an errors array:

{
  "data": null,
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/submissions"
  },
  "meta": {},
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "employee relationship is required"
    }
  ]
}

Query Parameters

Parameter	Purpose	Example
`page[number]`	Page number (default `1`)	`?page[number]=2`
`page[size]`	Page size (default `25`, max `100`)	`?page[size]=50`
`filter[field]`	Resource filtering per endpoint allow-list	`?filter[active]=true`
`sort`	Comma-separated fields, prefix with `-` for desc	`?sort=-created_at,name`
`include`	Sideload related resources	`?include=campaign_periods,content_versions`

Common Status Codes

Status	Meaning
`200`	Success
`201`	Created
`204`	Deleted / no response body
`400`	Bad request (missing required relationships, malformed payload)
`401`	Missing, invalid, or expired API key
`403`	Authenticated user has no current account
`404`	Resource not found in the current account scope
`422`	Validation error

Endpoint Map

Resource	Methods	Paths
API Keys	GET, POST, DELETE, POST validate	`/api/v1/api_keys`, `/api/v1/api_keys/:id`, `/api/v1/api_keys/validate`
Campaigns	GET, POST, GET by id, PATCH, DELETE	`/api/v1/campaigns`, `/api/v1/campaigns/:id`
Campaign Periods	GET nested index, POST nested create, GET by id, PATCH	`/api/v1/campaigns/:campaign_id/campaign_periods`, `/api/v1/campaign_periods/:id`
Content Versions	GET nested index, POST nested create, GET by id, PATCH	`/api/v1/campaigns/:campaign_id/content_versions`, `/api/v1/content_versions/:id`
Employees	GET, POST, GET by id, PATCH, DELETE	`/api/v1/employees`, `/api/v1/employees/:id`
Submissions	GET, POST, GET by id, PATCH, parse single, parse all, nested GET/POST	`/api/v1/submissions`, `/api/v1/submissions/:id`, `/api/v1/submissions/:id/parse_spin`, `/api/v1/submissions/parse_spin_all`, `/api/v1/campaign_periods/:campaign_period_id/submissions`
Content Pieces	GET nested index, GET by id, PATCH	`/api/v1/submissions/:submission_id/content_pieces`, `/api/v1/content_pieces/:id`
Nudges	GET index	`/api/v1/nudges`

Nested Routes

/api/v1/campaigns/:campaign_id/campaign_periods for campaign-specific periods
/api/v1/campaigns/:campaign_id/content_versions for campaign-specific content versions
/api/v1/campaign_periods/:campaign_period_id/submissions for period-scoped submissions
/api/v1/submissions/:submission_id/content_pieces for submission-scoped generated pieces

AI-Friendly Schema

Use /api/v1/api.json for a full machine-readable API reference containing endpoints, request contracts, and response schemas.