GET /v1/collections/:collectionId

Retrieve a single collection by ID, including all content items. This is the primary endpoint for fetching content to display in broadcast graphics.

Request

curl -H "X-API-Key: your-api-key" \
  https://api.interplai.app/v1/collections/col_abc123

const response = await fetch(
  'https://api.interplai.app/v1/collections/col_abc123',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const collection = await response.json();

Path parameters

Parameter	Type	Description
collectionId	string	Unique collection identifier

Response

{
  "id": "col_abc123",
  "name": "Match Day Social Feed",
  "contentType": "SOCIAL_POST",
  "stagingContentCount": 1,
  "liveContentCount": 2,
  "createdDate": "2026-01-10T08:00:00.000Z",
  "lastModifiedDate": "2026-01-18T10:35:00.000Z",
  "stagingContents": [
    {
      "id": "content_001",
      "fullName": "Sophie Hammer",
      "username": "sophiehammer",
      "source": "FACEBOOK",
      "message": "What a strike! Absolutely incredible goal",
      "profileImageUrl": "https://graph.facebook.com/sophie_h/picture",
      "media": [
        {
          "mediaUrl": "https://media.dizplai.com/social-media/2026/01/fb/0.jpg",
          "mediaType": "image/jpeg"
        }
      ],
      "publishedAt": "2026-01-18T10:30:00.000Z",
      "lastModifiedDate": "2026-01-18T10:35:00.000Z"
    }
  ],
  "liveContents": [
    {
      "id": "content_002",
      "fullName": "James Rodriguez",
      "username": "@jamesrodriguez",
      "source": "WHATSAPP",
      "message": "Unbelievable atmosphere at the stadium tonight! #MatchDay",
      "profileImageUrl": "https://example.com/profile/james_r.jpg",
      "media": [],
      "publishedAt": "2026-01-18T10:28:00.000Z",
      "lastModifiedDate": "2026-01-18T10:35:00.000Z"
    },
    {
      "id": "content_003",
      "fullName": "Premier League",
      "username": "@premierleague",
      "source": "INSTAGRAM",
      "message": "GOAL! What a way to open the scoring",
      "profileImageUrl": "https://instagram.com/pl_avatar.jpg",
      "media": [
        {
          "mediaUrl": "https://media.dizplai.com/social-media/2026/01/ig/goal.mp4",
          "mediaType": "video/mp4"
        }
      ],
      "publishedAt": "2026-01-18T10:25:00.000Z",
      "lastModifiedDate": "2026-01-18T10:35:00.000Z"
    }
  ],
  "meta": {
    "totalItems": 3,
    "page": 0,
    "pageSize": 3
  }
}

Response fields

Collection

Field	Type	Description
id	string	Unique collection identifier
name	string	Collection display name
contentType	string	Content type (see Content Types)
stagingContentCount	integer	Number of staging content items
liveContentCount	integer	Number of live content items
createdDate	string	ISO 8601 creation timestamp
lastModifiedDate	string	ISO 8601 last update timestamp
stagingContents	array	Array of staging content items
liveContents	array	Array of live content items
meta	object	Pagination metadata

Content item

Field	Type	Description
id	string	Unique content item identifier
fullName	string | null	Author display name
username	string | null	Author handle (e.g. @techwriter)
source	string	Source platform (see Sources)
message	string	The post text content
profileImageUrl	string | null	Author avatar URL
media	array	Attached media items
publishedAt	string	ISO 8601 original publish timestamp
lastModifiedDate	string	ISO 8601 last update timestamp

Media item

Field	Type	Description
mediaUrl	string	URL to the media asset
mediaType	string	MIME type (e.g. image/jpeg, video/mp4)

Conditional requests (ETags)

The response includes an ETag header. Use it with If-None-Match to avoid re-downloading unchanged data:

# First request — note the ETag in the response
curl -i -H "X-API-Key: your-api-key" \
  https://api.interplai.app/v1/collections/col_abc123
# Response includes: ETag: "2026-01-18T10:35:00.000Z"

# Subsequent request — send the ETag back
curl -H "X-API-Key: your-api-key" \
  -H 'If-None-Match: "2026-01-18T10:35:00.000Z"' \
  https://api.interplai.app/v1/collections/col_abc123
# Returns 304 Not Modified if unchanged

See Caching for more details.

Error responses

Status	Code	Description
401	MISSING_API_KEY / INVALID_API_KEY	Authentication failure
404	COLLECTION_NOT_FOUND	Collection does not exist
502	BAD_GATEWAY	Upstream service error
503	SERVICE_UNAVAILABLE	Service temporarily unavailable