Thing API

The Thing API manages persistent entities through four routes:

• POST /thing/create
• POST /thing/update
• POST /thing/archive
• POST /thing/delete

Contract Notes

• Request body must be JSON.
• Unknown fields are rejected (strict parsing).
• Authorization: Bearer <token> is required only when gateway auth is enabled.

Common Fields

Field	Type	Required	Notes
channel_id	string	Yes	Target channel ID.
password	string	Yes	Channel password, 8-128 chars.
op_id	string	No	Idempotency key. If missing, gateway generates one and echoes it in response.

Route-Level Required Fields

Route	Hard required business fields
/thing/create	observed_at
/thing/update	thing_id, observed_at
/thing/archive	thing_id, observed_at
/thing/delete	thing_id, observed_at

Payload Fields and Rules

Field	Type	Required	Rules
thing_id	string	Update/Archive/Delete	Must be omitted on create; generated by gateway on create.
title	string	No (recommended on create)	Product semantics recommend providing title on create; gateway currently does not reject missing title.
description	string	No	Empty string is treated as absent.
tags	string[]	No	Max 32 items, each max 64 chars, deduplicated after trim.
primary_image	string	No	Optional URL, max 2048 chars.
images	string[]	No	Max 32 items, each max 2048 chars, deduplicated after trim.
created_at	number	No	Allowed only on create; defaults to observed_at when absent.
deleted_at	number	No	Allowed only on delete; defaults to observed_at when absent.
external_ids	object	No	Key format: [A-Za-z0-9_:.\-], key <= 64; value must be string or null (null deletes key).
location_type + location_value	string + string	Pair	Must appear together. location_type: `physical
observed_at	number	Yes	Unix seconds; used as occurred-at for this thing dispatch.
attrs	object	No	Object patch; null value means delete key. Arrays are rejected; nested object depth is one level.
metadata	object	No	Scalar values only (string/number/bool), key <= 64, value <= 512.

Example: Create

curl -X POST https://gateway.pushgo.dev/thing/create \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "06J0FZG1Y8XGG14VTQ4Y3G10MR",
    "password": "pass-1234",
    "title": "Living Room Thermometer",
    "observed_at": 1713750000,
    "tags": ["sensor", "temperature"],
    "attrs": { "temperature": 22.5 }
  }'

Example Response

{
  "success": true,
  "data": {
    "channel_id": "06J0FZG1Y8XGG14VTQ4Y3G10MR",
    "op_id": "op-20260422-001",
    "thing_id": "8a1fc4b3d9f04fd2857f92f66f7cc5d1",
    "accepted": true
  },
  "error": null,
  "error_code": null
}