https://api.tightknit.ai/admin/v0). It covers everything that changes in the v1 API:
- Before you start: what to check before you send your first v1 request.
- What changes: changes that apply to every endpoint, such as IDs, pagination and errors.
- Endpoint by endpoint: the v1 call that replaces each v0 call, and what differs.
- Examples: complete code for common flows.
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.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 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 ishttps://api.tightknit.ai/v1.
Several resources have new names, and actions that lived on a nested path are now their own resources:
Permissions
Permissions are grouped in families, such asapi: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.
A request without the permission it needs returns
403 with the code insufficient_scope. See the full permission list.
IDs
Most v1 objects have anid 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:
Webhook payloads carry the v1 IDs next to the IDs they always carried. See Webhooks.
Response bodies
In the v1 API:
- Creates, updates and actions return the full object, in the same shape a
GETreturns. - Deletes return the object’s type, its
idand"deleted": true. - Every response has a
Request-Idheader. Include it when you contact support.
Pagination
Lists in the v0 API tookpage 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:
- Set the page size with
limit, from 1 to 100. The default is 20. - To get the next page, pass the
next_cursorvalue asstarting_after. - When a response has no
next_cursor, you’re on the last page.
Requests
- Send write bodies as JSON with
Content-Type: application/json. Anything else returns415. File uploads are the exception and usemultipart/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’sparamfield names the parameter. - Leave out an optional field you don’t want to set. Sending
nullis valid only where a field’s reference says it acceptsnull. - 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 format:
See the full list of v1 error codes.
Rate limits
The v1 API limits requests per community, not per key. Each community gets these limits:
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
idfilter, up to 100 per call. - Look up many members at once with a repeated
emailorslack_profile_idfilter. - DM up to 50 people in one
POST /v1/slack_messagescall withdm_slack_profile_ids. - Wait for the time in
Retry-Afterbefore 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 asdescription reads as an object with two members:
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 asdoc, or plain text as text. A document you read from the v1 API can be sent back as is.
null to remove the field.
Convert Slack blocks to ProseMirror
If you sent Slackrich_text blocks to the v0 API, convert each element to its ProseMirror node:
For example, here is a v0 description and the v1
description.doc that replaces it:
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 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.GET api_key/me
UseGET /v1/api_key. It needs no permission, as before.
Response changes:
POST awards/{award_id}/assign
UsePOST /v1/award_assignments.
Request changes:
Behavior changes:
- The response is the award assignment. The v0 API returned no data.
- The request returns
400when the recipient is a deactivated member, a bot, or someone who hasn’t joined the community yet.
GET calendar_events
UseGET /v1/events.
Filter and sort changes:
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:
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
UsePOST /v1/events.
Request changes:
Behavior changes:
statustakesdraft,needs_approvalorpublished.reminders_configtakes only reminders 2, 10, 60, 1440 or 10080 minutes before the start.- An event no longer needs a
linkor alocation. - The response is the full event. The v0 API returned only its ID.
GET calendar_events/{calendar_event_id}
UseGET /v1/events/{event_id}.
Response changes:
In the v1 API,
status can also be cancelled.
DELETE calendar_events/{calendar_event_id}
UseDELETE /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
UsePATCH /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_idfrom thecalendar_event.user_registeredpayload. - Otherwise, find it with
GET /v1/event_participants?event_id=cevt_…&profile_id=prof_….
personal_join_linkmust be anhttporhttpsURL. Sendnullto remove it.- New: send
"is_registered": falseto 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.
GET feeds
UseGET /v1/feeds.
is_archivedandis_unlistedkeep their names.- New filters:
id,slug,visibility,slack_channel_idandsearch[contains].
GET feeds/{feed_id}
UseGET /v1/feeds/{feed_id} with the feed_ ID, which the v0 API returns in public_id.
Response changes:
integrations.slack is null for a feed with no Slack channel.
GET feeds/{feed_id}/posts
UseGET /v1/messages?feed_id=feed_…&type=post&is_published=true. feed_id repeats, so you can read several feeds at once.
sort replaces the v0 API’s sort values:
Other changes:
feed_id=homeisn’t available. List the feeds you want with a repeatedfeed_id.- New filters:
author_profile_id,parent_message_idandis_published. - The messages in the response change the same way as in
GET posts/{post_id}, below.
POST files
UsePOST /v1/files with multipart/form-data.
Request changes:
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,urlandthumbnail_url. - Uploads count toward the costly endpoints’ rate limit.
POST groups/{group_id}/members
UsePOST /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:
POST members
UsePOST /v1/profiles.
Request changes:
Behavior changes:
- The response is the member. There’s no
slack_inviteobject. A successful response withinviteset means the invitation was sent. - Every success returns
200. The v0 API returned201for a new member and200when it adopted a pending Slack invitation. - Inviting needs the
api:admin:slack-invitespermission on top ofapi:admin:members. - An email that already belongs to a member returns
409, as before.
POST members/check
UseGET /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:
See Check membership at sign-in for a full example.
POST members/{member_id}/deactivate
UsePOST /v1/profiles/{profile_id}/deactivate.
- The response is the member.
already_deactivatedis gone. Deactivating a deactivated member returns it unchanged. - A member linked to a Slack account returns
409with the codemanaged_by_slack. Remove them from Slack instead. - New:
POST /v1/profiles/{profile_id}/activate.
POST messages
UsePOST /v1/slack_messages.
Request changes:
Behavior changes:
- The response says where the message went:
channel_id,ts,message_id, andfailed_dm_slack_profile_idsfor any DM that couldn’t be sent. - Sending counts toward the costly endpoints’ rate limit.
GET posts/{post_id}
UseGET /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:
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,
referencesandpost_detail_display_format. - New:
type(postorcomment),parent_message_id,descriptionandfirst_published_at.
GET search
UseGET /v1/search. It needs api:admin:messages:read and counts toward the costly endpoints’ rate limit.
qis nowquery.typetakespostorcomment.sorttakesrelevanceornewest, as before.- Results are messages, paginated with
limitandstarting_after.
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.Send a personal join link
When a member registers for an event, thecalendar_event.user_registered webhook carries the participation’s ID. Set the member’s join link with one call:

