> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tightknit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from the Admin API v0

> Move your integration from the earlier Tightknit Admin API to the current version. See what changes across the API and how each endpoint maps.

This guide is for developers who maintain an integration built on the Admin API v0 (`https://api.tightknit.ai/admin/v0`). It covers everything that changes in the v1 API:

* [Before you start](#before-you-start): what to check before you send your first v1 request.
* [What changes](#what-changes): changes that apply to every endpoint, such as IDs, pagination and errors.
* [Endpoint by endpoint](#endpoint-by-endpoint): the v1 call that replaces each v0 call, and what differs.
* [Examples](#examples): complete code for common flows.

> [!NOTE]
>
> The v0 API keeps working while you migrate, so you can move one endpoint at a time.

## Before you start

**1. Use an sk\_ key**

The v1 API accepts only keys created in Studio, which start with `sk_`. It refuses legacy keys that start with `tk-` with `401 invalid_token`. To create a key, see [API Keys](https://docs.tightknit.ai/integrations/api-keys.md).

**2. Check that the v1 API is enabled for your community**

Call `GET https://api.tightknit.ai/v1/api_key` with your `sk_` key. A `403` with the code `api_not_enabled` means the v1 API isn't enabled for your community yet. Contact Tightknit support for assistance.

**3. Check the key's permissions**

The v1 API checks permissions differently from the v0 API. Read [Permissions](#permissions) and create a new key if yours doesn't fit. You can't edit a key's permissions after you create it.

## What changes

These changes apply to every v1 endpoint.

### Base URL and paths

The v1 base URL is `https://api.tightknit.ai/v1`.

Several resources have new names, and actions that lived on a nested path are now their own resources:

| v0 | v1 |
| - | - |
| `calendar_events` | `events` |
| `calendar_events/{id}/attendees` | `event_participants` |
| `members` | `profiles` |
| `posts`, `feeds/{id}/posts` | `messages` |
| `messages` (send to Slack) | `slack_messages` |
| `awards/{id}/assign` | `award_assignments` |
| `groups/{id}/members` | `group_memberships` |

### Permissions

Permissions are grouped in families, such as `api:admin:feeds`. The v1 API separates read access from write access within a family:

* The family permission, such as `api:admin:feeds`, grants both reads and writes.
* The family's read permission, such as `api:admin:feeds:read`, grants reads only. Every v1 read needs at least this permission.

The v0 API accepts only the family permission. A key with read-only access to a family works with the v1 API but not with the v0 API. If you use one key with both versions during the migration, give it read and write access.

Some operations need a different permission than you might expect:

| Operation | Permission it needs |
| - | - |
| Posts, comments and search | `api:admin:messages`. `api:admin:posts` and `api:admin:search` don't exist in the v1 API. |
| Expanding a related object with `expand` | Read access to that object's family, on top of the permission for the request. For example, `GET /v1/messages?expand=author` needs `api:admin:members:read`. |
| Inviting a member to Slack while creating them | `api:admin:slack-invites` |

A request without the permission it needs returns `403` with the code `insufficient_scope`. See the [full permission list](https://docs.tightknit.ai/v1/api-reference/introduction.md#permissions).

### IDs

Most v1 objects have an `id` with a short prefix for their type, such as `prof_9f2b8c1d4e5a` for a member or `cevt_4h2o89z6qlpw` for an event. Slack-keyed objects use their Slack IDs.

The v1 API doesn't accept the UUIDs and other IDs that the v0 API used. It also doesn't accept emails or Slack user IDs where it expects an ID.

If you stored v0 IDs, look up their v1 IDs:

| Resource | How to get the v1 ID |
| - | - |
| Feed | The v0 API returns it in the feed's `public_id` field. |
| Post or comment | The v0 API returns it in the post's `message_id` field. |
| Member | `GET /v1/profiles?email=…` or `GET /v1/profiles?slack_profile_id=…`. Both filters repeat, up to 100 values per call. |
| Event | Read the event's `slug` from the v0 API, then call `GET /v1/events?slug=…`. The filter repeats, up to 100 values per call. |
| Award | `GET /v1/awards?slug=…` |
| Group | `GET /v1/groups?slug=…` |
| File | Upload the file again with `POST /v1/files`. |

Webhook payloads carry the v1 IDs next to the IDs they always carried. See [Webhooks](#webhooks).

### Response bodies

| Aspect | v0 | v1 |
| - | - | - |
| Body | Wrapped in `{ "success": true, "data": … }` | The object itself, with no wrapper. Every object has an `object` field that names its type. |
| Success status | `201` from some creates | `200` for every success |

In the v1 API:

* Creates, updates and actions return the full object, in the same shape a `GET` returns.
* Deletes return the object's type, its `id` and `"deleted": true`.
* Every response has a `Request-Id` header. Include it when you contact support.

### Pagination

Lists in the v0 API took `page` and `per_page` and returned totals. Lists in the v1 API use a cursor and return no total counts.

A v1 list looks like this:

```json theme={null}
{
  "object": "list",
  "data": [],
  "url": "/v1/feeds",
  "next_cursor": "eyJ2YWx1ZSI6IjIwMjYtMDktMjVUMTQ6NTI6MjUuMDQ2WiIs..."
}
```

To page through a list:

* Set the page size with `limit`, from 1 to 100. The default is 20.
* To get the next page, pass the `next_cursor` value as `starting_after`.
* When a response has no `next_cursor`, you're on the last page.

> [!WARNING]
>
> A cursor works only with the filters and sort that produced it. If you change either while passing a cursor, the request returns `400`.

### Requests

* Send write bodies as JSON with `Content-Type: application/json`. Anything else returns `415`. File uploads are the exception and use `multipart/form-data`.
* Send only the parameters the v1 API declares. The v0 API ignored parameters it didn't know. The v1 API refuses them with `400 invalid_request`, and the error's `param` field names the parameter.
* Leave out an optional field you don't want to set. Sending `null` is valid only where a field's reference says it accepts `null`.
* Format dates as RFC 3339 strings, as in the v0 API.

### Errors

v0 errors had the shape `{ "success": false, "error": { "code", "message", "hint" } }`. v1 errors use the [problem details](https://www.rfc-editor.org/rfc/rfc9457) format:

```json theme={null}
{
  "type": "about:blank",
  "title": "Invalid request",
  "status": 400,
  "detail": "Unknown parameter page",
  "code": "invalid_request",
  "param": "page",
  "request_id": "req_2ccb940dd8c94b5ca7887c40b5043240"
}
```

v1 codes are lowercase. The common codes map like this:

| v0 code | v1 code |
| - | - |
| `UNAUTHORIZED` | `unauthorized` (no key) or `invalid_token` (a key that isn't valid) |
| `INSUFFICIENT_SCOPE` | `insufficient_scope` |
| `NOT_FOUND` | `not_found` |
| `INVALID_ARGUMENT`, `INVALID_REQUEST`, `INVALID_PAGINATION_PARAMETERS` | `invalid_request` |
| `FEATURE_RESTRICTED` | `feature_not_enabled` |
| `RATE_LIMIT_EXCEEDED` | `rate_limited` |
| `INTERNAL_ERROR` | `internal_error` |

See the [full list of v1 error codes](https://docs.tightknit.ai/v1/api-reference/introduction.md#errors).

### Rate limits

The v1 API limits requests per community, not per key. Each community gets these limits:

| Request type | Limit per minute |
| - | - |
| Reads | 3,000 |
| Writes | 1,500 |
| Calls to a few costly endpoints, such as search, file uploads, deleting an event and sending a Slack message | 60 |

A throttled request returns `429` with the code `rate_limited` and a `Retry-After` header.

The other rate limit headers lost their `X-` prefix. For example, `X-RateLimit-Limit` is now `RateLimit-Limit`.

To stay under the limits:

* Read many objects in one call with the repeatable `id` filter, up to 100 per call.
* Look up many members at once with a repeated `email` or `slack_profile_id` filter.
* DM up to 50 people in one `POST /v1/slack_messages` call with `dm_slack_profile_ids`.
* Wait for the time in `Retry-After` before you retry.

### Formatted text

The v0 API returned formatted text as Slack blocks, with separate reference lists for mentions. The v1 API never returns Slack blocks or Slack markdown.

#### Read formatted text

The v1 API uses one shape for every formatted text field. A field such as `description` reads as an object with two members:

| Member | Content |
| - | - |
| `doc` | The content as a ProseMirror JSON document. Its root carries `"version": 1`, the version of the document format. |
| `text` | The same content as plain text. |

```json theme={null}
"description": {
  "doc": { "type": "doc", "version": 1, "content": [ ... ] },
  "text": "Join Ada Lovelace for a live demo."
}
```

A field with no content is `null`. Mentions in the document name members by their `prof_` ID, and channels name their feed by its `feed_` ID.

#### Write formatted text

Send the same object with exactly one member: the document as `doc`, or plain text as `text`. A document you read from the v1 API can be sent back as is.

```json theme={null}
{ "description": { "text": "Join us for a live demo." } }
```

Send `null` to remove the field.

> [!WARNING]
>
> Event descriptions and recaps are also posted to Slack, so they accept only what Slack can show. Anything else, such as a heading, an image or a nested list, returns `400` with a `detail` that names it.

#### Convert Slack blocks to ProseMirror

If you sent Slack `rich_text` blocks to the v0 API, convert each element to its ProseMirror node:

| Slack block element | ProseMirror node |
| - | - |
| `rich_text_section` | `paragraph` |
| `rich_text_list` with `style: "bullet"` | `bulletList` of `listItem`, each holding a `paragraph` |
| `rich_text_list` with `style: "ordered"` | `orderedList` of `listItem`, each holding a `paragraph` |
| `rich_text_quote` | `blockquote` holding `paragraph` nodes |
| `rich_text_preformatted` | `codeBlock` holding `text` |
| `text` with `style` `bold`, `italic`, `strike` or `code` | `text` with the marks `bold`, `italic`, `strike` or `code` |
| `link` with `url` | `text` with a `link` mark whose `href` is the URL |
| `user` with `user_id` | `mention` with `slack_profile_id`, or with `profile_id` for a `prof_` ID |
| `channel` with `channel_id` | `channel` with `slack_channel_id`, or with `feed.id` for a `feed_` ID |
| `emoji` with `name` | `emoji` with `name` |

For example, here is a v0 description and the v1 `description.doc` that replaces it:

```json v0 theme={null}
{
  "blocks": [
    {
      "type": "rich_text",
      "elements": [
        {
          "type": "rich_text_section",
          "elements": [
            { "type": "text", "text": "Join " },
            { "type": "user", "user_id": "U0BRY4S6LNQ" },
            { "type": "text", "text": " for a live demo.", "style": { "bold": true } }
          ]
        }
      ]
    }
  ]
}
```

```json v1 theme={null}
{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Join " },
        { "type": "mention", "attrs": { "slack_profile_id": "U0BRY4S6LNQ" } },
        { "type": "text", "text": " for a live demo.", "marks": [{ "type": "bold" }] }
      ]
    }
  ]
}
```

### Webhooks

Webhooks work the same as before: same subscriptions, same signatures, same events.

Their payloads now carry v1 IDs next to the IDs they always carried. Store the v1 IDs. See [IDs in payloads](https://docs.tightknit.ai/api-reference/webhooks.md#ids-in-payloads) for the fields.

## Endpoint by endpoint

This table maps each v0 endpoint to the v1 endpoint that replaces it. The sections below follow the order of the table and describe what changes for each one.

| v0 | v1 |
| - | - |
| `GET /admin/v0/api_key/me` | `GET /v1/api_key` |
| `POST /admin/v0/awards/{award_id}/assign` | `POST /v1/award_assignments` |
| `GET /admin/v0/calendar_events` | `GET /v1/events` |
| `POST /admin/v0/calendar_events` | `POST /v1/events` |
| `GET /admin/v0/calendar_events/{calendar_event_id}` | `GET /v1/events/{event_id}` |
| `DELETE /admin/v0/calendar_events/{calendar_event_id}` | `DELETE /v1/events/{event_id}` |
| `PATCH /admin/v0/calendar_events/{calendar_event_id}/attendees` | `PATCH /v1/event_participants/{event_participant_id}` |
| `GET /admin/v0/feeds` | `GET /v1/feeds` |
| `GET /admin/v0/feeds/{feed_id}` | `GET /v1/feeds/{feed_id}` |
| `GET /admin/v0/feeds/{feed_id}/posts` | `GET /v1/messages?feed_id=…&type=post&is_published=true` |
| `POST /admin/v0/files` | `POST /v1/files` |
| `POST /admin/v0/groups/{group_id}/members` | `POST /v1/group_memberships` |
| `POST /admin/v0/members` | `POST /v1/profiles` |
| `POST /admin/v0/members/check` | `GET /v1/profiles?email=…` |
| `POST /admin/v0/members/{member_id}/deactivate` | `POST /v1/profiles/{profile_id}/deactivate` |
| `POST /admin/v0/messages` | `POST /v1/slack_messages` |
| `GET /admin/v0/posts/{post_id}` | `GET /v1/messages/{message_id}` |
| `GET /admin/v0/search` | `GET /v1/search` |

### GET api\_key/me

Use `GET /v1/api_key`. It needs no permission, as before.

Response changes:

| v0 | v1 |
| - | - |
| `tenant` | `community_name` |
| `type` | Removed, since the v1 API accepts only one kind of key |
| None | New fields: `id`, `name`, `obfuscated_value` and `created_at` |

### POST awards/\{award\_id}/assign

Use `POST /v1/award_assignments`.

Request changes:

| v0 | v1 |
| - | - |
| `award_id` in the path | `award_id` in the body |
| `recipient` as `{ "email" }`, `{ "slack_user_id" }` or `{ "profile_id" }` | `profile_id` |
| `sender` | `given_by_id` |
| `send_anonymously` | `given_anonymously`, which now also needs `given_by_id` |
| None | `notify`, which defaults to `true`. Set it to `false` to skip the Slack notifications. Webhooks still fire. |

Behavior changes:

* The response is the award assignment. The v0 API returned no data.
* The request returns `400` when the recipient is a deactivated member, a bot, or someone who hasn't joined the community yet.

See [Give an award to members by email](#give-an-award-to-members-by-email) for a full example.

### GET calendar\_events

Use `GET /v1/events`.

> [!WARNING]
>
> When you leave out `status`, the v1 API returns events in every status, including `cancelled`. The v0 API returned only published events. Send `status=published` to keep the v0 API's results. `status` repeats.

Filter and sort changes:

| v0 | v1 |
| - | - |
| `time_filter`, `reference_date`, `date_filter` | Date ranges on `start_date` and `end_date`, which take `gt`, `gte`, `lt` and `lte`. See the queries below. |
| `tag_ids` | `tag_id`, repeated once per tag. See the note on tag matching below. |
| `published_to_site` | `publish_to_site` |
| `feed_id`, `is_unlisted` | Same names |
| None | New filters: `id`, `slug`, `title[contains]` and `created_at` ranges |

`sort` takes `start_date` or `created_at`, with a leading `-` for descending. The default is `-created_at`.

Use these queries in place of the v0 date filters:

| To get | Send |
| - | - |
| Upcoming events | `end_date[gte]=<now>&sort=start_date` |
| Past events | `end_date[lt]=<now>&sort=-start_date` |
| Events overlapping the 24 hours after a time, as `date_filter` returned | `start_date[lte]=<time + 24 hours>&end_date[gte]=<time>` |

Tag matching also changes. In the v1 API, `tag_id` returns events with any of the tags. The v0 API matched any tag within a tag group and all tag groups at once. To get the v0 API's results, call once per tag group and keep the events that appear in every response.

### POST calendar\_events

Use `POST /v1/events`.

> [!WARNING]
>
> The v1 API creates events as drafts unless you send `status`. A draft isn't announced in Slack, isn't on the community site and sends no reminders. Send `"status": "published"` to keep the v0 API's behavior.

Request changes:

| v0 | v1 |
| - | - |
| `description: { "text" }` | `description: { "text" }` |
| `description: { "blocks" }` | `description: { "doc" }`, a ProseMirror document. See [Formatted text](#formatted-text). |
| `recap` | `recap`, the same way |
| `publish_to_slack_channels` | `integrations.slack.published_channel_ids` |
| `luma_event_id` | `integrations.luma.event_id` |
| `hosts`, `speakers` as emails, Slack user IDs or member IDs | `host_profile_ids`, `speaker_profile_ids` as `prof_` IDs |
| `cover_image_file_id` as a v0 file ID | `cover_image_file_id` as a `file_` ID from `POST /v1/files` with `file_category=calendar-event-cover` |

Behavior changes:

* `status` takes `draft`, `needs_approval` or `published`.
* `reminders_config` takes only reminders 2, 10, 60, 1440 or 10080 minutes before the start.
* An event no longer needs a `link` or a `location`.
* The response is the full event. The v0 API returned only its ID.

### GET calendar\_events/\{calendar\_event\_id}

Use `GET /v1/events/{event_id}`.

Response changes:

| v0 | v1 |
| - | - |
| `description_slack_blocks` and its references | `description`, with its `doc` and `text` |
| `recap_slack_blocks` and its references | `recap`, with its `doc` and `text` |
| `luma_event_id` | `integrations.luma.event_id` |
| `published_to` | `integrations.slack.published_channels`, with `expand=slack_channels` |
| `tags` | `tag_links`, with `expand=tag_links` |
| `cover_image_url` | `cover_image_file_id`, and the file with `expand=cover_image_file` |
| `attendees_count` | `registrants_count` |
| `hosts`, `speakers` | `GET /v1/event_participants?event_id=…&is_host=true` (or `is_speaker=true`) |

In the v1 API, `status` can also be `cancelled`.

### DELETE calendar\_events/\{calendar\_event\_id}

Use `DELETE /v1/events/{event_id}`.

* The response is `{ "object": "event", "id": …, "deleted": true }`.
* Deleting an event counts toward the costly endpoints' rate limit.

### PATCH calendar\_events/\{calendar\_event\_id}/attendees

Use `PATCH /v1/event_participants/{event_participant_id}` with `personal_join_link`.

The v0 API identified the attendee by event and member. The v1 API identifies the participation by its own `calp_` ID. To get that ID:

* In a webhook flow, use `participant_public_id` from the `calendar_event.user_registered` payload.
* Otherwise, find it with `GET /v1/event_participants?event_id=cevt_…&profile_id=prof_…`.

Other changes:

* `personal_join_link` must be an `http` or `https` URL. Send `null` to remove it.
* New: send `"is_registered": false` to unregister the member.
* The participation must already exist. The v0 API could add someone who had never interacted with the community. To register a member in the v1 API, use `POST /v1/event_participants`.
* The response is the participant. The v0 API returned no data.

See [Send a personal join link](#send-a-personal-join-link) for a full example.

### GET feeds

Use `GET /v1/feeds`.

* `is_archived` and `is_unlisted` keep their names.
* New filters: `id`, `slug`, `visibility`, `slack_channel_id` and `search[contains]`.

### GET feeds/\{feed\_id}

Use `GET /v1/feeds/{feed_id}` with the `feed_` ID, which the v0 API returns in `public_id`.

Response changes:

| v0 | v1 |
| - | - |
| `id` (UUID) and `public_id` | `id` |
| `is_site_posting_enabled` | `allow_site_posting` |
| `allow_selected_answer` | `selected_answers_enabled` |
| `slack_channel_id`, `sync_all_incoming_messages`, `stores_new_messages` | `integrations.slack.channel_id`, `.sync_all_incoming_messages`, `.stores_new_messages` |
| `slack_channel_name`, `slack_channel_is_private`, `slack_channel_num_members` | `integrations.slack.channel.name`, `.is_private`, `.num_members`, with `expand=slack_channel` |
| `slack_channel_topic_slack_blocks`, `slack_channel_purpose_slack_blocks` | `integrations.slack.channel.topic`, `.purpose` (formatted text), with `expand=slack_channel` |
| `banner_file_url` | `banner_file_id`, and the file with `expand=banner_file` |
| `preset` | Removed |

`integrations.slack` is `null` for a feed with no Slack channel.

### GET feeds/\{feed\_id}/posts

Use `GET /v1/messages?feed_id=feed_…&type=post&is_published=true`. `feed_id` repeats, so you can read several feeds at once.

> [!WARNING]
>
> Without `is_published=true`, the v1 API also returns posts that aren't published: drafts, posts held for review, and Slack messages that were never published to the community site. The v0 API returned only published posts.

`sort` replaces the v0 API's sort values:

| v0 | v1 |
| - | - |
| `newest` | `-created_at`, the default |
| `oldest` | `created_at` |
| `most-recent-activity` | `-latest_activity_at` |

Other changes:

* `feed_id=home` isn't available. List the feeds you want with a repeated `feed_id`.
* New filters: `author_profile_id`, `parent_message_id` and `is_published`.
* The messages in the response change the same way as in `GET posts/{post_id}`, below.

### POST files

Use `POST /v1/files` with `multipart/form-data`.

Request changes:

| v0 | v1 |
| - | - |
| `file` | `file` |
| `filename` | `filename`, up to 100 characters from letters, digits, `.`, `_` and `-` |
| `description` | `description`, up to 150 characters |
| `size` | Not needed |
| None | `file_category`, required: where the image will be used, such as `calendar-event-cover` |

Behavior changes:

* The v1 API accepts only images that fit their category. The v0 API also accepted documents, audio, video and archives. The v1 API doesn't host those.
* The response is the file, with a `file_` ID, `url` and `thumbnail_url`.
* Uploads count toward the costly endpoints' rate limit.

### POST groups/\{group\_id}/members

Use `POST /v1/group_memberships` with `group_id` and `profile_id`. The v0 `user` object is gone.

The response is the membership. Adding someone who is already a member of the group returns their existing membership with `200`.

The request fails in these cases:

| Case | Response |
| - | - |
| The member is deactivated, is a bot, or hasn't joined yet | `400` |
| The group is at its plan's member limit | `400` |
| The community doesn't have groups | `403` with the code `feature_not_enabled` |

### POST members

Use `POST /v1/profiles`.

Request changes:

| v0 | v1 |
| - | - |
| `email`, `full_name` | `email`, `full_name` |
| `avatar_url_original` | `avatar_url`, an `http` or `https` URL |
| `invite_to_slack` | `integrations.slack.invite` |
| `slack_channel_ids` | `integrations.slack.invite_channel_ids` |

> [!WARNING]
>
> Inviting to Slack is all or nothing. If the invitation can't be sent, the v1 API returns an error and creates no member. The v0 API created the member and reported the failed invitation. To create the member without an invitation, retry without `integrations.slack`.

Behavior changes:

* The response is the member. There's no `slack_invite` object. A successful response with `invite` set means the invitation was sent.
* Every success returns `200`. The v0 API returned `201` for a new member and `200` when it adopted a pending Slack invitation.
* Inviting needs the `api:admin:slack-invites` permission on top of `api:admin:members`.
* An email that already belongs to a member returns `409`, as before.

### POST members/check

Use `GET /v1/profiles?email=…`. It needs `api:admin:members:read`.

The email moves from the request body to the query string. The match ignores letter case, as before.

Read the result from the list:

| Result | v0 | v1 |
| - | - | - |
| The address doesn't belong to a member | `is_member: false` | An empty `data` list |
| The member is deactivated | `is_deactivated` | `data[0].is_deactivated` |
| The member was erased | `is_forgotten: true` | Not returned, so an erased member looks like a non-member |

See [Check membership at sign-in](#check-membership-at-sign-in) for a full example.

### POST members/\{member\_id}/deactivate

Use `POST /v1/profiles/{profile_id}/deactivate`.

* The response is the member. `already_deactivated` is gone. Deactivating a deactivated member returns it unchanged.
* A member linked to a Slack account returns `409` with the code `managed_by_slack`. Remove them from Slack instead.
* New: `POST /v1/profiles/{profile_id}/activate`.

### POST messages

Use `POST /v1/slack_messages`.

Request changes:

| v0 | v1 |
| - | - |
| `channel` with a channel ID | `channel_id` |
| `channel` with a Slack user ID, to send a DM | `dm_slack_profile_ids`, up to 50 Slack user IDs |
| `text` | `text`, up to 3,000 characters, or `blocks`, up to 50 Slack blocks. Send one of the two. |
| `thread_ts` | `thread_ts`, which needs `channel_id` |
| None | `identity`, which chooses who the message comes from: `community` (the default, and the v0 API's behavior) or `bot` |
| None | `publish_to_site`, which also publishes a channel message to the community site, when the channel's feed accepts posts |

Behavior changes:

* The response says where the message went: `channel_id`, `ts`, `message_id`, and `failed_dm_slack_profile_ids` for any DM that couldn't be sent.
* Sending counts toward the costly endpoints' rate limit.

### GET posts/\{post\_id}

Use `GET /v1/messages/{message_id}` with the `msg_` ID, which the v0 API returns in `message_id`. The v1 API doesn't accept the older post IDs.

Response changes:

| v0 | v1 |
| - | - |
| `id` (older post ID) and `message_id` | `id` |
| `content_created_at` | `created_at` |
| `body_plaintext` | `body.text` |
| `body_prosemirror` | `body.doc` |
| `notice_prosemirror` | `notice`, with its `doc` and `text` |
| `author` | `author_profile_id`, and the member with `expand=author` |
| `feed` | `feed_id`, and the feed with `expand=feed` |
| `slack_message` | `integrations.slack`: `channel_id`, `ts` and `permalink` |
| `cover_image_url` | `cover_image_file_id`, and the file with `expand=cover_image_file` |

Other changes:

* The v1 API also returns unpublished messages, where the v0 API returned only published posts. Check `is_published`.
* The reply count is `replies_count`, and it includes unpublished replies.
* Removed: reaction counts, the selected answer, `references` and `post_detail_display_format`.
* New: `type` (`post` or `comment`), `parent_message_id`, `description` and `first_published_at`.

### GET search

Use `GET /v1/search`. It needs `api:admin:messages:read` and counts toward the costly endpoints' rate limit.

* `q` is now `query`.
* `type` takes `post` or `comment`.
* `sort` takes `relevance` or `newest`, as before.
* Results are messages, paginated with `limit` and `starting_after`.

Content resources aren't searchable here. Use `GET /v1/content_resources?search[contains]=…` instead. It matches part of the title or description without ranking results, and it needs `api:admin:content:read`.

## Examples

### Check membership at sign-in

In the v0 API, you posted the email and read three flags. In the v1 API, you filter profiles by email and check the first result.

```javascript v0 theme={null}
const response = await fetch("https://api.tightknit.ai/admin/v0/members/check", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TIGHTKNIT_API_KEY}`,
  },
  body: JSON.stringify({ email }),
});
const { data } = await response.json();
const isActiveMember = data.is_member && !data.is_deactivated && !data.is_forgotten;
```

```javascript v1 theme={null}
const url = new URL("https://api.tightknit.ai/v1/profiles");
url.searchParams.set("email", email);

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${TIGHTKNIT_API_KEY}` },
});
const { data } = await response.json();
const isActiveMember = data.length > 0 && !data[0].is_deactivated;
```

### Send a personal join link

When a member registers for an event, the `calendar_event.user_registered` webhook carries the participation's ID. Set the member's join link with one call:

```javascript theme={null}
await fetch(
  `https://api.tightknit.ai/v1/event_participants/${payload.participant_public_id}`,
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${TIGHTKNIT_API_KEY}`,
    },
    body: JSON.stringify({ personal_join_link: joinUrl }),
  }
);
```

### Give an award to members by email

The v0 API took an email per recipient. In the v1 API, look up the members first, up to 100 emails per call, then give the award to each member:

```javascript theme={null}
const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${TIGHTKNIT_API_KEY}`,
};

const lookup = new URL("https://api.tightknit.ai/v1/profiles");
for (const email of emails) lookup.searchParams.append("email", email);
lookup.searchParams.set("limit", "100");

const { data: members } = await (await fetch(lookup, { headers })).json();

for (const member of members) {
  await fetch("https://api.tightknit.ai/v1/award_assignments", {
    method: "POST",
    headers,
    body: JSON.stringify({ award_id: "awrd_7m3x9k4t8plz", profile_id: member.id }),
  });
}
```


## Related topics

- [API Keys](https://docs.tightknit.ai/integrations/api-keys.md)
- [Tightknit Admin API v1 Introduction](https://docs.tightknit.ai/v1/api-reference/introduction.md)
- [Tutorial: Simultaneous Events Across Multiple Zoom Accounts](https://docs.tightknit.ai/events/tutorials/multiple-zoom-accounts.md)
- [Retrieve the calling API key](https://docs.tightknit.ai/v1/api-reference/api-keys/retrieve-the-calling-api-key.md)
- [Cancel a composition’s scheduled send](https://docs.tightknit.ai/v1/api-reference/compositions/cancel-a-composition’s-scheduled-send.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.