Metaobjects

Metaobjects are standalone custom content types that merchants define and manage independently from products, customers, or any other resource. A metaobject type defines the structure (fields), and entries are instances of that type.

Metaobjects reuse the metafield type system — field definitions on a type are metafield definitions, and entry values are metafield values. This means all value types, validation rules, and serialization from the Metafields API apply to metaobject fields.

Metaobjects require the Custom Data extension to be enabled.

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

Use cases

• Brand profiles — name, logo, bio, website
• Size guides — size chart data per product category
• Influencer cards — name, photo, social links, bio
• FAQ entries — question + answer pairs
• Store locations — address, hours, coordinates

Metaobjects are not a CMS — no versioning, no drafts, no publishing workflows, no localization per entry. For content management, use a dedicated CMS and store the CMS entry ID in a metafield.

Endpoints — Types

Method	Path	Auth	Description
GET	/v1/store/metaobjects	Secret	List types
POST	/v1/store/metaobjects	Secret	Create a type
GET	/v1/store/metaobjects/{slug}	Secret	Get a type
PATCH	/v1/store/metaobjects/{slug}	Secret	Update a type
DELETE	/v1/store/metaobjects/{slug}	Secret	Archive a type

Endpoints — Fields

Method	Path	Auth	Description
POST	/v1/store/metaobjects/{slug}/fields	Secret	Add a field to a type
PATCH	/v1/store/metaobjects/{slug}/fields/{field}	Secret	Update a field
DELETE	/v1/store/metaobjects/{slug}/fields/{field}	Secret	Remove a field

Endpoints — Entries

Method	Path	Auth	Description
GET	/v1/metaobjects/{slug}/entries	Publishable	List entries
GET	/v1/metaobjects/{slug}/entries/{id}	Publishable	Get an entry
POST	/v1/metaobjects/{slug}/entries	Secret	Create an entry
PATCH	/v1/metaobjects/{slug}/entries/{id}	Secret	Update an entry
DELETE	/v1/metaobjects/{slug}/entries/{id}	Secret	Delete an entry

---

List types

GET /v1/store/metaobjects

Returns all metaobject types for the store.

Request

curl https://api.hydrajs.dev/v1/store/metaobjects \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "mot_abc123def456ghij",
			"internal_key": "mo_1",
			"slug": "influencer",
			"label": "Influencer",
			"archived": false,
			"created_at": "2026-08-22T10:00:00Z",
			"updated_at": "2026-08-22T10:00:00Z"
		}
	]
}

---

Create a type

POST /v1/store/metaobjects

Creates a new metaobject type. Add fields to the type after creation via the field endpoints.

Request body

Field	Type	Required	Description
label	string	Yes	Display name (1–100 chars)
slug	string	No	API identifier (1–64 chars, ^[a-z0-9_]+$). Auto-generated from label if omitted

Request

curl -X POST https://api.hydrajs.dev/v1/store/metaobjects \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Influencer"}'

Response 201

{
	"data": {
		"id": "mot_abc123def456ghij",
		"internal_key": "mo_1",
		"slug": "influencer",
		"label": "Influencer",
		"archived": false,
		"created_at": "2026-08-22T10:00:00Z",
		"updated_at": "2026-08-22T10:00:00Z"
	}
}

---

Get a type

GET /v1/store/metaobjects/{slug}

Returns a single metaobject type by slug.

Request

curl https://api.hydrajs.dev/v1/store/metaobjects/influencer \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

Type object.

---

Update a type

PATCH /v1/store/metaobjects/{slug}

Updates the label or slug of a metaobject type.

Request body

Field	Type	Required	Description
label	string	No	New display name
slug	string	No	New API identifier

Request

curl -X PATCH https://api.hydrajs.dev/v1/store/metaobjects/influencer \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Brand Ambassador"}'

Response 200

Updated type object.

---

Archive a type

DELETE /v1/store/metaobjects/{slug}

Archives the type. Entries and their values are preserved but become invisible. The slug is freed for reuse.

Request

curl -X DELETE https://api.hydrajs.dev/v1/store/metaobjects/influencer \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

Add a field

POST /v1/store/metaobjects/{slug}/fields

Adds a field definition to a metaobject type. Fields use the same type system as metafields — see supported value types.

Request body

Field	Type	Required	Description
label	string	Yes	Field display name (1–100 chars)
slug	string	No	Field slug (auto-generated from label if omitted)
description	string	No	Helper text (max 255 chars)
value_type	string	Yes	Value type (see metafields docs)
choices	string[]	No	Predefined values (for compatible types)
required	boolean	No	Default false
storefront_visible	boolean	No	Default true

Request

curl -X POST https://api.hydrajs.dev/v1/store/metaobjects/influencer/fields \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Bio", "value_type": "multi_line_text"}'

Response 201

Metafield definition object.

---

Update a field

PATCH /v1/store/metaobjects/{slug}/fields/{field}

Updates a field’s label, slug, description, choices, or visibility. Cannot change value_type.

Request

curl -X PATCH https://api.hydrajs.dev/v1/store/metaobjects/influencer/fields/bio \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Biography", "required": true}'

Response 200

Updated definition object.

---

Remove a field

DELETE /v1/store/metaobjects/{slug}/fields/{field}

Archives the field definition. Existing values are preserved but no longer visible.

Request

curl -X DELETE https://api.hydrajs.dev/v1/store/metaobjects/influencer/fields/bio \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

List entries

GET /v1/metaobjects/{slug}/entries

Returns a paginated list of entries for a metaobject type.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1–250)
cursor	string	-	Pagination cursor from a previous response

Request

curl https://api.hydrajs.dev/v1/metaobjects/influencer/entries?limit=10 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "moe_abc123def456ghij",
			"type_id": "mot_abc123def456ghij",
			"display_name": "Sarah Chen",
			"created_at": "2026-08-22T10:00:00Z",
			"updated_at": "2026-08-22T10:00:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 1
	}
}

---

Get an entry

GET /v1/metaobjects/{slug}/entries/{id}

Returns a single entry with all field values.

Request

curl https://api.hydrajs.dev/v1/metaobjects/influencer/entries/moe_abc123 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "moe_abc123def456ghij",
		"type_id": "mot_abc123def456ghij",
		"display_name": "Sarah Chen",
		"fields": {
			"bio": {
				"slug": "bio",
				"label": "Bio",
				"type": "multi_line_text",
				"choices": null,
				"value": "Fitness creator with 2M followers"
			},
			"age": {
				"slug": "age",
				"label": "Age",
				"type": "integer",
				"choices": null,
				"value": 28
			}
		},
		"created_at": "2026-08-22T10:00:00Z",
		"updated_at": "2026-08-22T10:00:00Z"
	}
}

---

Create an entry

POST /v1/metaobjects/{slug}/entries

Creates a new entry. Field values can be set in the same request.

Request body

Field	Type	Required	Description
display_name	string	Yes	Human-readable name (1–200 chars)
fields	object	No	Field values keyed by slug

Request

curl -X POST https://api.hydrajs.dev/v1/metaobjects/influencer/entries \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Sarah Chen",
    "fields": {
      "bio": "Fitness creator with 2M followers",
      "age": 28
    }
  }'

Response 201

Entry object with hydrated fields (same shape as GET).

---

Update an entry

PATCH /v1/metaobjects/{slug}/entries/{id}

Updates display name and/or field values. Only provided fields are affected.

Request body

Field	Type	Required	Description
display_name	string	No	New display name
fields	object	No	Field values to set. Send null to clear a field

Request

curl -X PATCH https://api.hydrajs.dev/v1/metaobjects/influencer/entries/moe_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"age": 29}}'

Response 200

Updated entry object with hydrated fields.

---

Delete an entry

DELETE /v1/metaobjects/{slug}/entries/{id}

Permanently deletes an entry and all its field values. This action cannot be undone.

Request

curl -X DELETE https://api.hydrajs.dev/v1/metaobjects/influencer/entries/moe_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

The type object

Field	Type	Description
id	string	Unique ID (prefix: mot_)
internal_key	string	Internal key (mo_1, mo_2, …) — immutable
slug	string	API identifier — changeable
label	string	Display name
archived	boolean	Whether the type is archived
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

The entry object

Field	Type	Description
id	string	Unique ID (prefix: moe_)
type_id	string	Parent type ID
display_name	string	Human-readable label
fields	object	Field values keyed by slug (present on GET single entry, create, and update responses)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp