Skip to content

Response Shapes

ssavutu edited this page Mar 15, 2026 · 5 revisions

V1 Response Shapes

Shared

Pagination Fields (for list responses)

{
  "items": [],
  "limit": 20,
  "offset": 0,
  "total": 143,
  "has_more": true
}

AuthorOverview

{
  "id": 123,
  "display_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe"
}

ArticleOverview

{
  "id": 456,
  "title": "New CMS Launch",
  "authors": [
    {
      "id": 123,
      "display_name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  ],
  "published_at": "2026-03-11T18:25:43Z",
  "categories": ["engineering"],
  "excerpt": "Short summary text",
  "photo_url": "https://cdn.example.com/image.jpg",
  "slug": "new-cms-launch",
  "status": "published",
  "is_featured": false
}

GalleryItem

{
  "id": 201,
  "file_name": "hero-banner.jpg",
  "url": "https://cdn.example.com/media/hero-banner.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 482193,
  "alt_text": "Homepage hero banner",
  "width": 1920,
  "height": 1080
}

MediaOverview

{
  "id": 201,
  "file_name": "hero-banner.jpg",
  "url": "https://cdn.example.com/media/hero-banner.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 482193,
  "width": 1920,
  "height": 1080,
  "alt_text": "Homepage hero banner"
}

Media

{
  "id": 201,
  "file_name": "hero-banner.jpg",
  "url": "https://cdn.example.com/media/hero-banner.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 482193,
  "width": 1920,
  "height": 1080,
  "alt_text": "Homepage hero banner",
  "caption": "Spring launch campaign",
  "created_at": "2026-03-11T18:25:43Z",
  "updated_at": "2026-03-11T18:25:43Z"
}

Homepage

GET /v1/homepage

{
  "new": [],
  "developing_stories": [],
  "columns": [],
  "major_sections": [
    {
      "section_slug": "news",
      "section_name": "News",
      "items": []
    }
  ]
}
  • new: ArticleOverview[] (13 max)
  • developing_stories: ArticleOverview[] (5 max)
  • columns: ArticleOverview[] (5 max)
  • major_sections[].items: ArticleOverview[] (5 max each)

Authors

GET /v1/authors

{
  "items": [],
  "limit": 20,
  "offset": 0,
  "total": 143,
  "has_more": true
}
  • items: Author[]

GET /v1/authors/{id}

{
  "id": 123,
  "display_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "created_at": "2026-03-11T18:25:43Z",
  "updated_at": "2026-03-11T18:25:43Z"
}

GET /v1/authors/{id}/articles

{
  "items": [],
  "limit": 20,
  "offset": 0,
  "total": 55,
  "has_more": true
}
  • items: ArticleOverview[]

Articles

GET /v1/articles

{
  "items": [],
  "limit": 20,
  "offset": 0,
  "total": 85,
  "has_more": true
}
  • items: ArticleOverview[]

GET /v1/sections/{section_slug}/articles

{
  "section": {
    "slug": "news",
    "name": "News"
  },
  "subsections": [
    {
      "slug": "local",
      "name": "Local"
    },
    {
      "slug": "world",
      "name": "World"
    }
  ],
  "articles": {
    "items": [],
    "limit": 20,
    "offset": 0,
    "total": 85,
    "has_more": true
  }
}

GET /v1/subsections/{subsection_slug}/articles

{
  "subsection": {
    "slug": "lovetriangle",
    "name": "Love Triangle",
    "section_slug": "columns"
  },
  "articles": {
    "items": [],
    "limit": 20,
    "offset": 0,
    "total": 23,
    "has_more": true
  }
}

Media

GET /v1/media

{
  "items": [],
  "limit": 20,
  "offset": 0,
  "total": 812,
  "has_more": true
}
  • items: MediaOverview[]

GET /v1/media/{id}

Media

GET /v1/media/gallery

{
  "items": [
    {
      "id": 201,
      "file_name": "hero-banner.jpg",
      "url": "https://cdn.example.com/media/hero-banner.jpg",
      "alt_text": "Homepage hero banner",
      "width": 1920,
      "height": 1080,
      "mime_type": "image/jpeg"
    }
  ],
  "limit": 60,
  "offset": 0,
  "total": 812,
  "has_more": true
}