Shapes

Shapes define the structure of things in a repository. These endpoints manage shapes directly — as an alternative to creating and revising shapes through the commit endpoint.

All paths are prefixed with /api/repos/:orgName/:repoName.

---

GET /shapes

List all shapes in a repository.

Auth: None (public repos). Private repos require authentication.

Response 200

[
  {
    "name": "Sensor",
    "kind": "shape",
    "active": true,
    "version": {
      "version": 2,
      "operation": "revise",
      "data": {
        "fields": { "location": "string", "type": "string", "unit": "string" }
      },
      "dataHash": "a1b2c3d4"
    }
  }
]

Example

curl "https://api.warmhub.ai/api/repos/myorg/myrepo/shapes"

---

GET /shapes/:shapeName

Get a single shape by name.

Auth: None (public repos). Private repos require authentication.

Path Parameters

Parameter	Type	Description
shapeName	string	Shape name (URL-encoded)

Response 200

{
  "name": "Sensor",
  "kind": "shape",
  "active": true,
  "version": {
    "version": 2,
    "operation": "revise",
    "data": {
      "fields": { "location": "string", "type": "string", "unit": "string" }
    },
    "dataHash": "a1b2c3d4"
  }
}

Errors

Code	Status	Description
NOT_FOUND	404	Shape not found

Example

curl "https://api.warmhub.ai/api/repos/myorg/myrepo/shapes/Sensor"

---

POST /shapes

Create a new shape.

Auth: Required, repo:write scope.

Request Body

Field	Type	Required	Description
name	string	Yes	Shape name
fields	object	Yes	Schema definition object

The name field also accepts shapeName as an alias.

Response 201

{
  "name": "Sensor",
  "operation": "add",
  "version": 1,
  "dataHash": "a1b2c3d4"
}

Errors

Code	Status	Description
ALREADY_EXISTS	409	A shape with this name already exists
VALIDATION_ERROR	400	Invalid shape name or fields
RESERVED_NAME	400	The name is reserved by the system
RATE_LIMITED	429	Too many shape creation requests. Honor Retry-After before retrying.

Example

curl -X POST https://api.warmhub.ai/api/repos/myorg/myrepo/shapes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sensor",
    "fields": { "location": "string", "type": "string" }
  }'

---

PATCH /shapes/:shapeName

Revise a shape’s fields. This creates a new version of the shape.

Auth: Required, repo:write scope.

Path Parameters

Parameter	Type	Description
shapeName	string	Shape name (URL-encoded)

Request Body

Field	Type	Required	Description
fields	object	Yes	Updated field definitions

Response 200

{
  "name": "Sensor",
  "operation": "revise",
  "version": 2,
  "dataHash": "e5f6g7h8"
}

Errors

Code	Status	Description
NOT_FOUND	404	Shape not found
VALIDATION_ERROR	400	Invalid fields
RATE_LIMITED	429	Too many shape update requests. Honor Retry-After before retrying.

Example

curl -X PATCH https://api.warmhub.ai/api/repos/myorg/myrepo/shapes/Sensor \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": { "location": "string", "type": "string", "unit": "string" }
  }'

---

DELETE /shapes/:shapeName

Delete a shape. This deactivates the shape itself. Things and assertions under the shape are not automatically deactivated — deactivate them separately if needed.

Auth: Required, repo:write scope.

Path Parameters

Parameter	Type	Description
shapeName	string	Shape name (URL-encoded)

Response 200

{
  "ok": true
}

Errors

Code	Status	Description
NOT_FOUND	404	Shape not found
RATE_LIMITED	429	Too many shape delete requests. Honor Retry-After before retrying.

Example

curl -X DELETE https://api.warmhub.ai/api/repos/myorg/myrepo/shapes/Sensor \
  -H "Authorization: Bearer <token>"