Collections
Read and change your collections from your own code: items, views, rules, runs, approvals and which agents have access. Reading needs collections:read. Changing items, running rules and deciding approvals needs collections:write. Setting collections up, which covers fields, statuses, views, rules and agent access, needs collections:manage.
How keys behave here
- Changes made with a key are recorded as made by the API, on behalf of the person who created the key.
- A key decides approvals as the person who created it. A key with no creator can't decide them and gets
403. - Rules saved with a key are saved turned off, so someone can check them in the dashboard and turn them on.
Endpoints
All paths start with /api/v1/collections.
| Method & path | Ability | Notes |
|---|---|---|
GET / | read | Every collection with its item count. ?trash=1 lists the trash |
POST / | manage | { name, description, fields, statuses? } |
GET /{id} | read | The collection with its views, rules and agents |
PUT /{id} | manage | Any of name, description, fields, statuses, primary_field |
DELETE /{id}, POST /{id}/restore | manage | Move to the trash, or bring back |
GET /{id}/items | read | See listing items |
POST /{id}/items | write | { values, status? } |
GET /{id}/items/{item} | read | |
PUT /{id}/items/{item} | write | { values?, status?, version }, see versions |
DELETE /{id}/items/{item}, POST …/restore | write | Move to the trash, or bring back |
GET /{id}/items/{item}/history | read | Every change, newest first |
GET / POST /{id}/views, PUT / DELETE /{id}/views/{view} | read / manage | PUT replaces the whole view |
GET / POST /{id}/rules, PUT / DELETE /{id}/rules/{rule} | read / manage | PUT replaces the whole rule |
POST /{id}/rules/{rule}/run | write | { item_id? } → { started, more } |
GET /{id}/runs | read | Filter by item_id, rule_id and state |
GET / PUT /{id}/agents | read / manage | PUT { agents: [{ bot_id, access }] } replaces the list |
GET /{id}/analytics | read | since, until, bucket (day or week), date_field, tz |
GET /members | read | Workspace members as { id, name }, for person fields |
GET /approvals | read | Filter by state (pending by default), collection_id, item_id |
POST /approvals/{id}/decide | write | { approve: true|false, note? } |
Lists take limit (1 to 200, 50 by default) and offset, and reply with the rows, total, limit and offset, as described in pagination.
Listing items
GET /api/v1/collections/{id}/items takes these query parameters, all optional:
view_id- use a view's filters and sort.filters- URL-encoded JSON such as{"match":"all","items":[{"field":"channel","op":"equals","value":"blog"}]}, up to 20 conditions. With a view, these narrow the view's own filters.sort- JSON such as[{"field":"publish_at","desc":false}]. It replaces the view's sort. Without one, items come newest first.q- search text, up to 200 characters. It looks through text, web and email addresses, phone numbers and option names.ids- up to 200 item ids, separated by commas.trash=1- list the trash instead.
curl "https://app.hania.ai/api/v1/collections/$COLLECTION_ID/items?q=launch&limit=50" \
-H "Authorization: Bearer $HANIA_API_KEY"Item values
An item's values are keyed by field id, and null clears a field. Text is a string, as are web addresses, email addresses and phone numbers. A number is a number and a checkbox is true or false. Money is {"amount": 12.5, "currency": "USD"}. A date is "YYYY-MM-DD", and a date and time is RFC 3339, returned in UTC. A choice is an option id, and multiple choice a list of option ids. A person is a user id, linked items a list of item ids, and a file is a media id or an https URL.
Field and option ids are made from their names when you leave them out, so a field called "Publish at" gets the id publish_at. When you update fields or statuses, send the whole list with the existing ids. A field sent without its id is treated as a new one.
Versions
Every item has a version, and an update must send the version you last read. Send only the values you're changing. If someone changed the item in the meantime, you get 412 with the code VERSION_CONFLICT, and data holds the item as it is now, so you can apply your change to that and try again.
curl -X PUT "https://app.hania.ai/api/v1/collections/$COLLECTION_ID/items/$ITEM_ID" \
-H "Authorization: Bearer $HANIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"values":{"channel":"social"},"status":"in_progress","version":3}'Errors
Besides the usual errors, a 400 with the code VALIDATION_FAILED also names the part of your request that's wrong in field, for example values.title or actions[0].on_reject. A plan limit returns 402 with COLLECTION_LIMIT_REACHED, COLLECTION_ITEM_LIMIT_REACHED or COLLECTION_RULE_LIMIT_REACHED.