Endpoints

V1 Endpoints

Conventions

• Pagination applies to all list endpoints unless noted:
  • Query: limit, offset
  • Response: items, limit, offset, total, has_more
• Taxonomy slugs must match Site Taxonomy.
• Invalid section_slug or subsection_slug returns 400 Bad Request.

Homepage

• GET /v1/homepage returns homepage buckets.
  • Sorting rule for all buckets:
    • primary: published_at DESC
    • secondary: is_featured DESC
  • Bucket sizing:
    • new: 13 stories
    • developing_stories: 5 stories
    • columns: 5 stories (parent section = columns)
    • major_sections: each section gets 5 stories

Authors

• GET /v1/authors returns paginated authors

  • Query params
    • limit: int
    • offset: int
    • sort_by: string — one of display_name, created_at, updated_at
    • sort_direction: string — asc, desc
    • article_id: int — optional author filter by article

• POST /v1/authors create author

  • Body (AuthorInput)
    • display_name: string
    • first_name?: string
    • last_name?: string
    • email?: string

• GET /v1/authors/{id} get author by id

• PUT /v1/authors/{id} replace author

• PATCH /v1/authors/{id} partial update author

• DELETE /v1/authors/{id} delete author

• GET /v1/authors/{id}/articles paginated articles by author

  • Query params
    • limit: int
    • offset: int
    • categories: string[]
    • sort_by: string — one of title, slug, created_at, published_at, status
    • sort_direction: string — asc, desc
    • status: string — draft, published

Articles

• GET /v1/articles returns paginated articles

  • Query params
    • limit: int
    • offset: int
    • categories: string[]
    • sort_by: string — one of title, slug, created_at, published_at, status
    • sort_direction: string — asc, desc
    • author_id: int
    • status: string — draft, published

• GET /v1/articles/{id} get article object

• POST /v1/articles create article

• PUT /v1/articles/{id} replace article

• PATCH /v1/articles/{id} update article

• DELETE /v1/articles/{id} delete article

Sections / Subsections

• Allowed section_slug values:

  • news, sports, opinion, columns, entertainment, comics-puzzles

• Allowed subsection_slug values:

  • academic-transformation, politics, transit, crime-policy-violations
  • mens-basketball, womens-basketball, big-5, philly-sports, field-hockey, mens-soccer, womens-soccer
  • science-tech, from-the-editor
  • the-love-triangle, tri-this-sweet-treat
  • movies, music, happening-in-philly, cooking, books, gaming, listicles
  • political-cartoons, crossword, sudoku

• GET /v1/sections/{section_slug}/articles paginated section feed

  • Includes articles from all subsections under the section.
  • Query params
    • limit: int
    • offset: int
    • author_id?: int
    • status?: string — draft, published
    • sort_by?: string — one of title, slug, created_at, published_at, status
    • sort_direction?: string — asc, desc

• GET /v1/subsections/{subsection_slug}/articles paginated subsection feed

  • Query params
    • limit: int
    • offset: int
    • author_id?: int
    • status?: string — draft, published
    • sort_by?: string — one of title, slug, created_at, published_at, status
    • sort_direction?: string — asc, desc

Media

• GET /v1/media returns a paginated list of media assets

  • Query params
    • limit: int
    • offset: int
    • query: string (search by filename)
    • mime_type: string (example: image/jpeg)
    • sort_by: string — one of file_name, created_at, updated_at, size_bytes
    • sort_direction: string — asc, desc
  • Response item shape: MediaOverview

• POST /v1/media create media metadata record

  • Body (MediaInput)
    • file_name: string
    • url: string
    • mime_type: string
    • alt_text?: string
    • caption?: string
  • Response shape: Media

• GET /v1/media/{id} get media asset

  • Response shape: Media

• PUT /v1/media/{id} replace media metadata

  • Body: same as MediaInput
  • Response shape: Media

• PATCH /v1/media/{id} partial update media metadata

  • Body (MediaPatch)
    • file_name?: string
    • alt_text?: string
    • caption?: string
  • Response shape: Media

• DELETE /v1/media/{id} delete media asset

  • Response: 204 No Content

• GET /v1/media/gallery frontend gallery endpoint

  • Query params
    • limit: int
    • offset: int
    • query?: string
    • mime_type?: string
    • sort_by?: string — one of file_name, created_at, updated_at, size_bytes
    • sort_direction?: string — asc, desc
  • Returns lightweight gallery cards (shape aligned to MediaOverview) optimized for UI grids.