Blogs

Blog posts are the primary content type in Forja. They support localization, categories, editorial workflow, document attachments, and RSS feeds.

Endpoints

Method	Path	Permission	Description
GET	/sites/{site_id}/blogs?page&per_page	Read	List all blogs (paginated)
GET	/sites/{site_id}/blogs/published?page&per_page	Read	List published blogs
GET	/sites/{site_id}/blogs/featured?limit	Read	List featured blogs
GET	/sites/{site_id}/blogs/{id}/similar?limit	Read	List similar blogs by taxonomy overlap
GET	/sites/{site_id}/blogs/by-slug/{slug}	Read	Get blog by slug
GET	/blogs/{id}	Read	Get blog by ID
GET	/blogs/{id}/detail	Read	Get blog with localizations, categories, and documents
POST	/blogs	Author	Create a blog post
PUT	/blogs/{id}	Author	Update a blog post
DELETE	/blogs/{id}	Editor	Soft delete a blog post
POST	/blogs/{id}/clone	Author	Clone a blog as a new Draft
POST	/blogs/{id}/review	Reviewer	Approve or request changes
GET	/blogs/{id}/localizations	Read	Get all localizations
POST	/blogs/{id}/localizations	Author	Create a localization
PUT	/blogs/localizations/{loc_id}	Author	Update a localization
DELETE	/blogs/localizations/{loc_id}	Editor	Delete a localization
GET	/sites/{site_id}/feed.rss	Read	RSS 2.0 feed of published posts
POST	/sites/{site_id}/blogs/bulk	Author/Editor	Bulk status update or delete

List Blogs

curl -H "X-API-Key: oy_live_abc123..." \
  "https://your-domain.com/api/v1/sites/{site_id}/blogs?page=1&per_page=10"

Response 200 OK -- Paginated list with data and meta fields.

Get Blog Detail

Returns the blog post with all localizations, assigned categories, and attached documents in a single response.

curl -H "X-API-Key: oy_live_abc123..." \
  https://your-domain.com/api/v1/blogs/{id}/detail

Create a Blog

curl -X POST \
  -H "X-API-Key: oy_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "site_ids": ["550e8400-..."],
    "slug": "my-first-post",
    "author": "John Doe",
    "status": "Draft"
  }' \
  https://your-domain.com/api/v1/blogs

Response 201 Created

Similar Blogs

Returns blogs similar to the given blog post, ranked by taxonomy overlap. Scoring: shared tags (+3 each), shared categories (+2 each), primary category match (+3 bonus), same author (+1). Only published blogs with a score > 0 are returned. If nothing is similar, the response is an empty array.

curl -H "X-API-Key: oy_live_abc123..." \
  "https://your-domain.com/api/v1/sites/{site_id}/blogs/{id}/similar?limit=3"

Query Parameters

Parameter	Default	Max	Description
limit	3	10	Number of similar blogs to return

Response 200 OK -- Array of BlogListItem objects sorted by relevance score (descending), then by published_date (most recent first).

Editorial Workflow

Content follows the lifecycle: Draft -> InReview -> Published (or Scheduled). Submitting content for review notifies reviewers. Reviewers can approve (moves to Published/Scheduled) or request changes (moves back to Draft).

curl -X POST \
  -H "X-API-Key: oy_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"action": "Approve"}' \
  https://your-domain.com/api/v1/blogs/{id}/review

RSS Feed

Returns an RSS 2.0 XML feed of the last 50 published blog posts. The response has Content-Type: application/rss+xml and is cached for 1 hour.

curl -H "X-API-Key: oy_live_abc123..." \
  https://your-domain.com/api/v1/sites/{site_id}/feed.rss

Bulk Actions

Perform bulk status updates or deletes on multiple blogs at once. Delete requires Editor role; status update requires Author role.

curl -X POST \
  -H "X-API-Key: oy_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "UpdateStatus",
    "ids": ["id1", "id2"],
    "status": "Published"
  }' \
  https://your-domain.com/api/v1/sites/{site_id}/blogs/bulk