> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/updates.md).
# Posts
Known as 'Updates' in the API.
A post is a message on the News Feed, or a note on a record such as a project, company or contact. Posts live at `/v2/updates`.
Posts don't work quite like other records. `GET /v2/updates` returns the News Feed, or searches posts, rather than listing a table (see [Reading posts](#reading-posts) below), and a post's permissions follow who wrote it, not the usual record rules (see [Who can change a post](#who-can-change-a-post)). Authentication, paging and errors are the same as everywhere else, and are covered in [Working with the API](/api/concepts.md).
{% hint style="info" %}
In tiny+ these are called **Posts**. The API calls the type `updates`, so its URL is `/v2/updates` and its records have `"flavour": "updates"`.
{% endhint %}
## Reading posts
There are three ways to read posts.
### The News Feed, or a search
`GET` `https://api.tiny.plus/v2/updates`
With no filters, you get the **News Feed**: the posts shared to it, pinned posts first, then the most recently updated.
With any filter below, you get a **search** of every post written by a person that the token's user can open, whether it was shared to the News Feed or only posted on a record. Posts tiny+ writes automatically, confidential notes, and posts on a confidential record the user can't open are left out. A search comes back newest first, always as an array.
| Parameter | Description |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text` | Words the posts must contain, in the post, its comments or its link. Separate alternatives with `\|` and groups with `,`: a post must match every group, and any word in a group will do. Words need at least three letters. `text=hospital\|clinic,ballarat` finds posts that mention hospital or clinic, and Ballarat. |
| `about` | Records the posts must be linked to, by id or name, in the same format as `text`. `about=1343\|1360,8` finds posts linked to project 1343 or 1360, and to company 8. |
| `staff` | A comma-separated list of team member ids. Returns the posts written by any of them. |
| `me` | Set to `1` for the posts written by the token's user. |
| `created_user`, `created_date`, `broadcast`, … | Any field in the [field reference](#field-reference), with the [filter grammar](/api/concepts/listing.md#filtering). `created_date=>2026-01-01` and `broadcast=1` finds this year's News Feed posts. |
| `sort` | A field and direction, such as `created_date desc`. You can sort by `created_date`, `modified_date`, `name` or `id`. A search is newest first unless you sort it. |
| `limit`, `start` | Paging. `limit` defaults to `15`, maximum `50`. |
| `return_format` | `array` returns `records` as an array. Recommended; a search always returns an array whatever you send. |
When a filter can't be applied, the response lists it under `dropped`, with the reason, rather than ignoring it. If you asked for `text` or `about` and none of the words or records could be used, no posts match.
```bash
curl "https://api.tiny.plus/v2/updates?text=fee|proposal|ab&limit=2&return_format=array" \
-H "Authorization: Bearer {{user_access_token}}"
```
```json
{
"total_records": 3,
"returned_records": 2,
"records": [
{
"id": "134783",
"description_plain": "There's a new opportunity with Hotel Hotel we should follow up on.",
"created_user": "1231",
"created_date": "2026-09-11 05:03:36.0000000",
"broadcast": "1",
"pinned": null,
"perm_edit": false,
"perm_delete": false,
"record_url": "https://crm.tiny.plus/post/134783"
}
],
"dropped": [
{ "item": "text", "field": "ab", "reason": "too short to search for; words need 3 letters or more" }
]
}
```
### The posts about a record
`GET` `https://api.tiny.plus/v2/updates/{{record_id}}`
The id in the path is the id of the **record** the posts are about — a project, company or contact — not the id of a post. For some record types this also includes the posts on the records linked to it: for a project, for example, the posts on its tasks and meetings.
`limit` (default `15`, maximum `50`), `start` and `return_format` work as above.
```bash
curl "https://api.tiny.plus/v2/updates/1343?return_format=array" \
-H "Authorization: Bearer {{user_access_token}}"
```
If there is no such record, or the token's user can't see it, the response is `404 {"error": "No related record."}`.
### One post by its id
`GET` `https://api.tiny.plus/v2/updates?single_id={{id}}`
Pass a post's id as `single_id`. The response has the same shape as a list, with one post in `records`. If there is no such post, or the token's user can't see it, `records` is empty.
```bash
curl "https://api.tiny.plus/v2/updates?single_id=134783&return_format=array" \
-H "Authorization: Bearer {{user_access_token}}"
```
{% hint style="info" %}
`single_id` finds any post the token's user could see on a feed: one on the News Feed, or one on a record they can open. A post that is neither comes back as if it didn't exist.
{% endhint %}
### Notes logged on a relationship plan
When someone logs a [relationship plan](/api/endpoints/relationship-plans.md) follow-up as done, their notes become an ordinary post on the company and the contacts it was with. Such a post carries `plan_touch`, which says what was logged:
```json
{
"plan_touch": {
"plan": { "id": 155147, "name": "Warm up a prospect" },
"touch_type": "email",
"date": "2026-09-27",
"did": "logged an email to Susan Aitchinson",
"contacts": [
{ "id": 62377, "name": "Susan Aitchinson" }
],
"step": "Introduction email",
"next_date": "2026-10-05"
}
}
```
`did` is the sentence tiny+ shows after the author's name, in plain text, and `contacts` are the people it names. `next_date` is the follow-up the plan booked next, or `null` when there isn't one. Other posts have no `plan_touch`.
## Creating a post
`POST` `https://api.tiny.plus/v2/updates`
```bash
curl -X POST "https://api.tiny.plus/v2/updates" \
-H "Authorization: Bearer {{user_access_token}}" \
-H "Content-Type: application/json" \
-d '{
"description": "Site visit went well. Revised fee proposal to follow.",
"related_id": "1343"
}'
```
```json
{
"id": "161129"
}
```
| Field | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | Required. The body of the post. Send plain text; HTML is stripped. The post's `name` is made from the start of it. |
| `related_id` | The id of a record the post is about — a project, company, contact or other record the token's user can open. The post appears on that record. |
| `extra_ids` | Other record ids to link the post to, as an array, or a comma-separated string such as `"8,1360"`. |
| `broadcast` | `1` to share the post to the News Feed, `0` to keep it on its record only. Shared by default. |
| `notify` | `false` to create the post without notifying anyone. Notifies by default. |
| `created_user` | Account admins only: the team member the post is attributed to. See [Permissions](/api/concepts/permissions.md#a-token-acts-as-a-person). |
| `selected_items` | Team member ids to @-mention, as an array. Each is notified and added to the post's team. |
Add `return_record=1` to get the whole new post back instead of just its id.
{% hint style="warning" %}
A post is shared to the News Feed unless you send `"broadcast": "0"` — even when it's about a confidential record. To keep a post on a confidential record out of everyone's News Feed, send `"broadcast": "0"`.
{% endhint %}
If `related_id`, or any of the `extra_ids`, isn't a record the token's user can see — it doesn't exist, has been deleted, belongs to another account, or is a confidential record hidden from them — nothing is posted, and the response names the field:
```json
{
"error": "Record not found (related_id)."
}
```
The status is `404`, and the message ends `(extra_ids)` for a bad entry in `extra_ids`. Leave `related_id` out (or empty) to post to the News Feed alone.
## Who can change a post
A post can be changed only by **the person who wrote it, or a News Feed admin** (a role account admins hold). This is not the usual record rule: a records admin, or someone merely linked to the post, cannot change it.
Every post you read carries `perm_edit` and `perm_delete`, which tell you whether this token may edit or delete that post. They already apply this rule, so a client should read them rather than work it out.
{% hint style="warning" %}
A post that tiny+ generated — one with a non-empty `update_type`, such as "Nick updated a project" — can still come back with `perm_edit: true` for its author. Only plain posts are meant to be edited, so offer Edit only when `perm_edit` is `true` **and** `update_type` is empty.
{% endhint %}
### Editing a post
`PUT` (or `PATCH`) `https://api.tiny.plus/v2/updates/{{id}}`
```bash
curl -X PATCH "https://api.tiny.plus/v2/updates/161129" \
-H "Authorization: Bearer {{user_access_token}}" \
-H "Content-Type: application/json" \
-d '{ "description": "Site visit went well. Fee proposal sent." }'
```
```json
{
"results": true
}
```
`description` is the field to change. Send `selected_items` to @-mention people in the new text; the response then also carries `mentions_added`.
`results` is `false` if the edit was refused by validation. If the token's user may not change the post, the response is `403 {"error": "You may not change this post: it is not yours."}`.
### Deleting a post
`DELETE` `https://api.tiny.plus/v2/updates/{{id}}`
```json
{
"results": true
}
```
`results` is `false` if the post couldn't be deleted. A post the token's user may not change gives `403 {"error": "You may not change this post: it is not yours."}`, and an id that matches no post gives `404 {"error": "Record not found."}`.
## Comments
Each post read carries its comments and likes in `social`:
```json
"social": {
"like_ids": ["191", "1231"],
"likers": [{ "id": "191", "name": "Maya Lin" }, { "id": "1231", "name": "Nick Smith" }],
"comments": [
{
"id": "161134",
"description": "Great news — I'll draft the fee.",
"created_date": "2026-09-29 23:23:08.0000000",
"created_user": "191",
"created_user_record": { "id": "191", "name": "Maya Lin", "role": "Marketing Manager", "record_url": "https://crm.tiny.plus/staff/191", "hero_thumb_uri": "…" },
"images": [],
"documents": [],
"perm_edit": false,
"perm_delete": true
}
]
}
```
`like_ids` are the ids of the people who have liked the post, in the order they liked it, and `likers` the same people by name. Each comment carries its own `perm_edit` and `perm_delete`: a comment can be edited by its author or a News Feed admin, and deleted by those or by the post's author.
### Adding a comment
`POST` `https://api.tiny.plus/v2/comments`
```bash
curl -X POST "https://api.tiny.plus/v2/comments" \
-H "Authorization: Bearer {{user_access_token}}" \
-H "Content-Type: application/json" \
-d '{ "update_id": "161129", "comment": "Great news, I will draft the fee." }'
```
```json
{
"id": "161134"
}
```
`update_id` is the post's id, and `comment` is the text. The post's author, and anyone else who has commented, are notified.
You can comment on any post you can open — the same posts [`single_id`](#one-post-by-its-id) returns. Any other `update_id` gets `404 {"error": "Post not found."}`, whether the post doesn't exist, has been deleted, belongs to another account, or is one the token's user can't see. If the comment can't be saved, the response is `500 {"error": "Could not add the comment."}`.
## Field reference
Most values come back as strings, including ids and numbers.
| Field | Type | Notes | Editable |
| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `id` | Number | The post's id. | No |
| `name` | Text | Made from the start of the description. | No |
| `description` | Text | The body of the post. Required on create. Send plain text. | Yes |
| `description_HTML` | Text | The body with links, @-mentions and embeds kept. | No |
| `description_plain` | Text | The body as plain text. | No |
| `broadcast` | Yes/no | `1` if the post is on the News Feed. Set on create; `1` by default. | Yes |
| `pinned` | Yes/no | `1` if the post is pinned to the top of the News Feed. Pinning is a News Feed admin action. | No |
| `update_type` | Text | Empty for a post someone wrote. Set for a post tiny+ generated. | No |
| `created_user` | Team member id | Who wrote the post. Account admins can set it on create; see [Attribution](/api/concepts/permissions.md#a-token-acts-as-a-person). | Admins only |
| `created_date` | Date-time (UTC) | When the post was created. | Admins only |
| `modified_user` | Team member id | Who last changed the post. | No |
| `modified_date` | Date-time (UTC) | When the post was last changed. | No |
| `created_user_record` | Object | The author's `id`, `name`, `role`, `record_url` and `hero_thumb_uri`. | No |
| `assigned_user` | Team member id | The team member the post is assigned to. | Yes |
| `record_url` | URL | The post's page in tiny+. | No |
| `social` | Object | `like_ids` and `likers`, and `comments` with each comment's `perm_edit` and `perm_delete`. See [Comments](#comments). | No |
| `attached` | Array | The records the post is linked to. Set on create with `related_id` and `extra_ids`. | No |
| `images` | Array | Images on the post, each with `id`, `name`, `hero_path_uri` and `hero_thumb_uri`. | No |
| `documents` | Array | Files on the post, each with `id`, `name` and `doctype` (the file's extension, such as `pdf`). Open one through [`GET /v2/attachments/{id}`](/api/endpoints/attachments.md). Each comment carries its own `documents` the same way. Absent when the post has none. | No |
| `perm_edit` | Yes/no | Whether this token may edit the post. See [Who can change a post](#who-can-change-a-post). | No |
| `perm_delete` | Yes/no | Whether this token may delete the post. | No |
| `plan_touch` | Object | Only on a post that holds the notes of a relationship plan follow-up. See [Notes logged on a relationship plan](#notes-logged-on-a-relationship-plan). | No |