Skip to main content
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: 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 is https://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 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: A request without the permission it needs returns 403 with the code insufficient_scope. See the full permission list.

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: 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 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:
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.
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 format:
v1 codes are lowercase. The common codes map like this: 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 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:
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.
Send null to remove the field.
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: 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

Use GET /v1/api_key. It needs no permission, as before. Response changes:

POST awards/{award_id}/assign

Use POST /v1/award_assignments. Request changes: 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 for a full example.

GET calendar_events

Use GET /v1/events.
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: 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

Use POST /v1/events.
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: 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: 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 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: 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.
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: 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: 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:

POST members

Use POST /v1/profiles. Request changes:
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: See 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: 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: 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.
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.
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:

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: