Content Pieces API
Content pieces are generated outputs from a submission/content-version pair.
Endpoints
GET /api/v1/submissions/:submission_id/content_piecesGET /api/v1/content_pieces/:idPATCH /api/v1/content_pieces/:id
Create/Delete: there are currently no create/delete endpoints for content pieces.
Filtering, Sorting, Include
- Nested index filters:
id,content_version_id,status,position - Nested index sort fields:
id,status,position,created_at,updated_at - Include:
submission,content_version - Valid
statusvalues:pending,generated,approved,published
GET /api/v1/submissions/:submission_id/content_pieces
curl -X GET "https://cases.shipmentbot.com/api/v1/submissions/15/content_pieces?sort=position&include=content_version" \
-H "Accept: application/json" \
-H "X-API-Key: csb_live_your_token_here"{
"data": [
{
"id": "31",
"type": "content_pieces",
"attributes": {
"status": "generated",
"position": 0,
"body": "Here is a polished LinkedIn draft...",
"image_url": null,
"generated_at": "2026-03-03T15:04:33.000Z",
"approved_at": null,
"published_at": null,
"created_at": "2026-03-03T15:04:33.000Z",
"updated_at": "2026-03-03T15:04:33.000Z"
},
"relationships": {
"submission": {
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31/relationships/submission",
"related": "https://cases.shipmentbot.com/api/v1/submissions/15"
},
"data": { "id": "15", "type": "submissions" }
},
"content_version": {
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31/relationships/content_version",
"related": "https://cases.shipmentbot.com/api/v1/content_versions/7"
},
"data": { "id": "7", "type": "content_versions" }
}
},
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31"
}
}
],
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/submissions/15/content_pieces?page%5Bnumber%5D=1&page%5Bsize%5D=25",
"first": "https://cases.shipmentbot.com/api/v1/submissions/15/content_pieces?page%5Bnumber%5D=1&page%5Bsize%5D=25",
"last": "https://cases.shipmentbot.com/api/v1/submissions/15/content_pieces?page%5Bnumber%5D=1&page%5Bsize%5D=25",
"next": null,
"prev": null
},
"meta": {
"page": {
"number": 1,
"size": 25,
"total_records": 1,
"total_pages": 1
}
}
}GET /api/v1/content_pieces/:id
curl -X GET "https://cases.shipmentbot.com/api/v1/content_pieces/31?include=submission,content_version" \
-H "Accept: application/json" \
-H "X-API-Key: csb_live_your_token_here"{
"data": {
"id": "31",
"type": "content_pieces",
"attributes": {
"status": "generated",
"position": 0,
"body": "Here is a polished LinkedIn draft...",
"image_url": null,
"generated_at": "2026-03-03T15:04:33.000Z",
"approved_at": null,
"published_at": null,
"created_at": "2026-03-03T15:04:33.000Z",
"updated_at": "2026-03-03T15:04:33.000Z"
},
"relationships": {
"submission": {
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31/relationships/submission",
"related": "https://cases.shipmentbot.com/api/v1/submissions/15"
},
"data": { "id": "15", "type": "submissions" }
},
"content_version": {
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31/relationships/content_version",
"related": "https://cases.shipmentbot.com/api/v1/content_versions/7"
},
"data": { "id": "7", "type": "content_versions" }
}
},
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31"
}
},
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31?include=submission,content_version"
},
"meta": {}
}PATCH /api/v1/content_pieces/:id
You can update attributes and optionally remap relationships using
data.relationships.submission.id and/or
data.relationships.content_version.id.
curl -X PATCH "https://cases.shipmentbot.com/api/v1/content_pieces/31" \
-H "Content-Type: application/json" \
-H "X-API-Key: csb_live_your_token_here" \
-d '{
"data": {
"type": "content_pieces",
"id": "31",
"attributes": {
"status": "approved",
"approved_at": "2026-03-05T18:55:00Z",
"body": "Approved LinkedIn post copy"
},
"relationships": {
"content_version": {
"data": { "type": "content_versions", "id": "7" }
}
}
}
}'{
"data": {
"id": "31",
"type": "content_pieces",
"attributes": {
"status": "approved",
"position": 0,
"body": "Approved LinkedIn post copy",
"image_url": null,
"generated_at": "2026-03-03T15:04:33.000Z",
"approved_at": "2026-03-05T18:55:00.000Z",
"published_at": null,
"created_at": "2026-03-03T15:04:33.000Z",
"updated_at": "2026-03-05T18:55:01.000Z"
},
"relationships": {
"submission": {
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31/relationships/submission",
"related": "https://cases.shipmentbot.com/api/v1/submissions/15"
},
"data": { "id": "15", "type": "submissions" }
},
"content_version": {
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31/relationships/content_version",
"related": "https://cases.shipmentbot.com/api/v1/content_versions/7"
},
"data": { "id": "7", "type": "content_versions" }
}
},
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31"
}
},
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31"
},
"meta": {}
}Error Examples
404 Submission Not Found (nested index)
{
"data": null,
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/submissions/999999/content_pieces"
},
"meta": {},
"errors": [
{
"status": "404",
"title": "Not Found",
"detail": "Submission not found"
}
]
}404 Content Piece Not Found
{
"data": null,
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/999999"
},
"meta": {},
"errors": [
{
"status": "404",
"title": "Not Found",
"detail": "Content piece not found"
}
]
}404 Related Submission/Content Version Not Found
{
"data": null,
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31"
},
"meta": {},
"errors": [
{
"status": "404",
"title": "Not Found",
"detail": "Related submission or content version not found for this account"
}
]
}422 Validation Error
{
"data": null,
"included": [],
"links": {
"self": "https://cases.shipmentbot.com/api/v1/content_pieces/31"
},
"meta": {},
"errors": [
{
"status": "422",
"title": "Validation Error",
"detail": "Position must be present for multi output content versions",
"source": {
"pointer": "/data/attributes/position"
}
}
]
}