Posts

Posts power your blog and static page content. Each post has a type (post for blog entries, page for static pages), a status workflow (draft, published, archived), and supports categories, tags, featured images, and SEO metadata.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/posts	Publishable	List posts
POST	/v1/posts	Secret	Create a post
GET	/v1/posts/{id}	Publishable	Get a post
PATCH	/v1/posts/{id}	Secret	Update a post
DELETE	/v1/posts/{id}	Secret	Delete a post
POST	/v1/posts/{id}/categories	Secret	Add categories to a post
DELETE	/v1/posts/{id}/categories/{category_id}	Secret	Remove a category from a post

---

List posts

GET /v1/posts

Returns a paginated list of posts and pages.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1-250)
cursor	string	-	Pagination cursor from a previous response
sort	string	created_at	Sort field: created_at, updated_at, title
order	string	desc	Sort direction: asc, desc
type	string	-	Filter by type: post, page
status	string	-	Filter by status: draft, published, archived
category_id	string	-	Filter by content category ID
tag	string	-	Filter by tag name
search	string	-	Search by title (max 200 chars)
expand	string	-	Include related data: categories, tags, featured_image
fields	string	-	Comma-separated fields to return

Request

curl "https://api.hydrajs.dev/v1/posts?type=post&status=published&expand=categories,tags" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "post_abc123def456ghij",
			"type": "post",
			"title": "Getting Started with Hydra",
			"handle": "getting-started-with-hydra",
			"excerpt": "A quick introduction to Hydra headless commerce.",
			"status": "published",
			"author_name": "Jane Smith",
			"published_at": "2026-08-24T12:00:00.000Z",
			"categories": [
				{ "id": "ccat_abc123def456ghij", "title": "Engineering", "handle": "engineering" }
			],
			"tags": [
				{ "id": "tag_abc123def456ghij", "name": "tutorials" }
			],
			"created_at": "2026-08-24T10:00:00.000Z",
			"updated_at": "2026-08-24T14:30:00.000Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 1
	}
}

---

Create a post

POST /v1/posts

Creates a new post or page. The handle is auto-generated from the title if not provided.

Request body

Field	Type	Required	Default	Description
title	string	Yes	-	Post title (1-255 chars)
handle	string	No	(from title)	URL slug (1-255 chars)
body	string	No	-	Post content, supports Markdown (max 500,000 chars)
excerpt	string	No	-	Short summary (max 1,000 chars)
type	string	No	"post"	"post" or "page"
status	string	No	"draft"	"draft", "published", or "archived"
author_name	string	No	-	Author display name (max 255 chars)
featured_image_id	string	No	-	Image ID from the media library
published_at	string	No	-	ISO 8601 publish date
category_ids	string[]	No	-	Content category IDs (max 20)
tags	string[]	No	-	Tag names (max 50, auto-created if new)
seo	object	No	-	SEO metadata with title and description
metadata	object	No	-	Custom key-value pairs

Request

curl -X POST https://api.hydrajs.dev/v1/posts \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Hydra",
    "body": "# Welcome\n\nThis is your first post.",
    "excerpt": "A quick introduction to Hydra headless commerce.",
    "type": "post",
    "status": "published",
    "author_name": "Jane Smith",
    "published_at": "2026-08-24T12:00:00.000Z",
    "category_ids": ["ccat_abc123def456ghij"],
    "tags": ["tutorials", "getting-started"]
  }'

Response 201

{
	"data": {
		"id": "post_abc123def456ghij",
		"type": "post",
		"title": "Getting Started with Hydra",
		"handle": "getting-started-with-hydra",
		"body": "# Welcome\n\nThis is your first post.",
		"excerpt": "A quick introduction to Hydra headless commerce.",
		"status": "published",
		"author_name": "Jane Smith",
		"featured_image": null,
		"published_at": "2026-08-24T12:00:00.000Z",
		"seo": { "title": null, "description": null },
		"metadata": {},
		"categories": [
			{ "id": "ccat_abc123def456ghij", "title": "Engineering", "handle": "engineering" }
		],
		"tags": [
			{ "id": "tag_abc123def456ghij", "name": "tutorials" },
			{ "id": "tag_klm789nop012qrst", "name": "getting-started" }
		],
		"created_at": "2026-08-24T10:00:00.000Z",
		"updated_at": "2026-08-24T10:00:00.000Z"
	}
}

---

Get a post

GET /v1/posts/{id}

Retrieves a single post or page by ID. Categories and tags are always included.

Request

curl https://api.hydrajs.dev/v1/posts/post_abc123def456ghij \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

Returns the full post object including body, categories, tags, and featured_image.

---

Update a post

PATCH /v1/posts/{id}

Partially updates a post or page. Only provided fields are modified.

Request body

All fields from Create a post are accepted, plus:

Field	Type	Description
create_redirect	boolean	Create a URL redirect when changing the handle

Request

curl -X PATCH https://api.hydrajs.dev/v1/posts/post_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

Response 200

Returns the updated post object.

---

Delete a post

DELETE /v1/posts/{id}

Soft-deletes a post or page. The handle is freed for reuse. A daily cron job purges soft-deleted posts after 30 days.

Request

curl -X DELETE https://api.hydrajs.dev/v1/posts/post_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

Add categories to a post

POST /v1/posts/{id}/categories

Associates one or more content categories with a post. Categories already associated are skipped.

Request body

Field	Type	Required	Description
category_ids	string[]	Yes	Content category IDs (1-20 items)

Request

curl -X POST https://api.hydrajs.dev/v1/posts/post_abc123def456ghij/categories \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_ids": ["ccat_def456ghi789jklm"]}'

Response 200

Returns the updated post object.

---

Remove a category from a post

DELETE /v1/posts/{id}/categories/{category_id}

Removes a content category association from a post. The category itself is not deleted.

Request

curl -X DELETE https://api.hydrajs.dev/v1/posts/post_abc123def456ghij/categories/ccat_def456ghi789jklm \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

The post object

Field	Type	Description
id	string	Unique ID (prefix: post_)
type	string	"post" or "page"
title	string	Post title
handle	string	URL slug (unique per store)
body	string	Post content (Markdown)
excerpt	string	Short summary
status	string	"draft", "published", or "archived"
author_name	string	Author display name
featured_image	object	Featured image with id, src, alt, width, height
published_at	string	ISO 8601 publish date
seo	object	SEO metadata (title, description)
metadata	object	Custom key-value pairs
categories	array	Associated content categories
tags	array	Associated tags
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp