Posts

File a post as an insight under a request

An insight is a customer's own words kept as evidence under a request — a quote, not a request of its own, and never returned by GET /v2/posts.

POST

/v2/posts/{id}/link-insight

curl --request POST \
  --url https://do.featurebase.app/v2/posts/{id}/link-insight \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "issueId": "507f1f77bcf86cd799439011",
  "linkSource": "manual"
}
'

{
  "access": {
    "companyExternalIds": [],
    "userIds": []
  },
  "anchor": {
    "commentId": "<string>",
    "conversationId": "<string>",
    "messageId": "<string>",
    "ranges": [
      {
        "end": 123,
        "start": 123
      }
    ],
    "sourceRecordId": "<string>",
    "submissionId": "<string>"
  },
  "assigneeId": "507f1f77bcf86cd799439013",
  "author": {
    "email": "john@example.com",
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "profilePicture": "https://cdn.example.com/avatars/john.png",
    "type": "customer"
  },
  "boardId": "507f1f77bcf86cd799439011",
  "commentCount": 5,
  "content": "<p>It would be great to have a dark mode option for the dashboard.</p>",
  "createdAt": "2023-12-12T00:00:00.000Z",
  "customFields": {
    "cf_effort": 3,
    "cf_priority": "high"
  },
  "deduped": true,
  "eta": "2025-01-01T00:00:00.000Z",
  "features": {
    "commentsEnabled": true
  },
  "groupKey": null,
  "id": "507f1f77bcf86cd799439011",
  "inReview": false,
  "insightSource": {
    "capturedBy": "manual",
    "channel": "slack",
    "conversationId": "<string>",
    "externalId": "<string>",
    "sourceLabel": "<string>",
    "url": "<string>"
  },
  "intakeMode": "request",
  "integrations": {
    "clickup": [
      {
        "id": "86a1b2c3d",
        "title": "Add dark mode support",
        "url": "https://app.clickup.com/t/86a1b2c3d"
      }
    ],
    "devops": [
      {
        "id": 1234,
        "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "projectName": "My Project",
        "title": "Add dark mode support",
        "url": "https://dev.azure.com/org/project/_workitems/edit/1234"
      }
    ],
    "github": [
      {
        "id": "1234567890",
        "number": "42",
        "repositoryFullName": "acme/backend",
        "repositoryName": "backend",
        "title": "Add dark mode support",
        "url": "https://github.com/acme/backend/issues/42"
      }
    ],
    "hubspot": [
      {

This endpoint turns the post {id} into an insight under the request issueId. Use it for the sentence a customer actually said; use attachTo on POST /v2/posts when the thing you are filing is a request in its own right and should stay one.

What changes

The post becomes an insight: kind is insight and linkedIssueId is the request.
It leaves the posts resource. GET /v2/posts/{id} answers 404 from then on, and it no longer appears in GET /v2/posts. Read it back through GET /v2/posts/{issueId}/insights, which is where it now lives.
Its author counts as a supporter of the request: the insight's upvoters are rolled onto the request (deduped by user, so a customer who had already voted is not counted twice) and the insight's author is subscribed to the request's updates. The request's upvotes goes up accordingly.
The request's linkedInsightCount is recounted from the live set of insights pointing at it.

Linking again to the same request is a no-op and returns the insight unchanged.

An insight that is already filed under a DIFFERENT request is MOVED — but only if nobody has confirmed that first link by hand. The old link is dropped first, and the old request is remembered as "not a match" so automatic matching never puts it back there. An insight whose link was already confirmed by a person (every link made through this endpoint counts as confirmed) is refused with 400 Insight is already linked to another issue. Detach it first. — call POST /v2/posts/{id}/unlink-insight first, then link it where you want it.

Which targets are refused

404 — no post with {id} in this workspace, or one the API key cannot see (Insight not found.); no request with issueId, or one the API key cannot see (Issue not found.).
400 — issueId equals {id} (a post cannot be linked to itself); the target is not a request (it is itself an insight, or a record — convert or restore it first); the target is a processed submission (atomizedAt — link to the requests that came out of it); the post being linked is a record (link the record's extracted insights instead); the post is already filed under another request by hand (unlink it first).
400 invalid_id — {id} or issueId is not a valid object id.

A merged, held-for-moderation, spam-held or closed target is not refused here: those guards apply to automatic (AI) attachment only, and a person linking by hand is trusted to mean it.

Response

The updated insight, in the standard post format (kind: 'insight', linkedIssueId set). The request it was linked to is not returned — fetch it with GET /v2/posts/{issueId} if you need its new upvotes and linkedInsightCount.

Body

issueId — the request to file this post under. Required.
linkSource — deprecated and ignored; a link made through the API is always a manual link.

Errors

Failures raised by the insight service (404 / 400 / 409) are returned as { "code": <status>, "message": "..." } rather than in the Stripe-style envelope the rest of this resource uses. The status code is the contract; do not parse the body shape.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Post unique identifier

Example: 507f1f77bcf86cd799439011

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

issueIdstringrequired

ID of the request this post becomes evidence for. Must be a request in this workspace that can still take evidence.

Example: 507f1f77bcf86cd799439011

linkSourceenum<string>deprecated

Deprecated and ignored. A link made through the API is always recorded as a manual link.

Available options: manual, ai

Response

Success

accessobjectrequired

Show child attributes

anchorobject | nullrequired

When kind is 'insight', where exactly the insight points back into its origin: an insight source record with character ranges into its fullText, or the native conversation/message/comment/post ids.

Show child attributes

assigneeIdstring | nullrequired

ID of the admin assigned to this post, null if unassigned

Example: 507f1f77bcf86cd799439013

authorobject | nullrequired

Show child attributes

boardIdstringrequired

Board (category) ID this post belongs to

Example: 507f1f77bcf86cd799439011

commentCountnumberrequired

Total number of comments

Example: 5

contentstringrequired

Post content in HTML format

Example: <p>It would be great to have a dark mode option for the dashboard.</p>

createdAtstringrequired

ISO 8601 timestamp when created

Example: 2023-12-12T00:00:00.000Z

customFieldsobjectrequired

Custom field values keyed by field ID

dedupedenum<boolean>

Present and true only on POST /v2/posts, when the request carried a source.externalId that already had a post. The existing post is returned unchanged with HTTP 200; a newly created post returns HTTP 201 without this field.

Available options: true

Example: true

etastring | nullrequired

Estimated completion time as ISO 8601 timestamp, null if not set

Example: 2025-01-01T00:00:00.000Z

featuresobjectrequired

Show child attributes

groupKeystring | nullrequired

When kind is 'insight', the triage grouping key (source record id, conversation id, origin post id, or the insight's own id for singletons). Legacy insights may be null and group as singletons.

idstringrequired

Unique identifier

Example: 507f1f77bcf86cd799439011

inReviewbooleanrequired

Whether the post is pending moderation review

Example: false

insightSourceobject | nullrequired

Provenance of an insight: which channel it came from and how it was captured.

Show child attributes

intakeModeenum<string>

Present only on POST /v2/posts: the intakeMode the post was processed under ('request' when the request named none). On an idempotent replay (deduped: true) this is the mode the post was ORIGINALLY created with.

Available options: request, feedback

Example: request

integrationsobjectrequired

Third-party integration links associated with this post

Show child attributes

isPinnedbooleanrequired

Whether the post is pinned to the top

Example: false

kindenum<string>required

Discriminates an actionable work item ('issue') from a customer submission whose claims were extracted into insights ('record' — not a work item). Defaults to 'issue' for all pre-existing posts. Default list responses return issues only; pass kind='record' to opt in. Raw signal ('insight') is never returned by the posts resource — insights are served by /v2/insights.

Available options: issue, insight, record

Example: issue

linkedInsightCountnumberrequired

Number of insights linked to this issue as supporting evidence. Only meaningful when kind is 'issue'.

Example: 0

linkedIssueIdstring | nullrequired

When kind is 'insight', the ID of the issue this insight supports. Null when the insight is unlinked or when kind is 'issue'.

objectenum<string>required

Object type identifier

Available options: post

Example: post

opportunityAmountnumber | nullrequired

Total opportunity amount from linked HubSpot deals and Salesforce opportunities

Example: 30000

portalHiddenbooleanrequired

True when the issue is hidden from portal/public surfaces. Missing stored values are returned as false.

Example: false

postUrlstringrequired

Full URL to view the post

Example: https://feedback.example.com/p/add-dark-mode-support

processingobject

On POST /v2/posts — queued: a processing run (claim extraction or the Organize rewrite) was enqueued and its result lands asynchronously on the post. skipped: nothing was enqueued; reason says which gate decided ('request_mode' for every intakeMode: 'request' create). existing: the create was an idempotent replay and the post was not processed again. On GET /v2/posts/{id} this field is present only for posts created with intakeMode: 'feedback' and reports how far that processing has got ('queued', 'processing', 'complete', 'needs_review', or 'skipped' with the same reason the create returned), with results listing what was made of the submission once the run has finished.

Show child attributes

slugstringrequired

URL-friendly slug

Example: add-dark-mode-support

statusobjectrequired

Show child attributes

tagsobject[]required

Tags attached to this post

Show child attributes

titlestringrequired

Post title

Example: Add dark mode support

updatedAtstringrequired

ISO 8601 timestamp when last modified

Example: 2023-12-13T00:00:00.000Z

upvotesnumberrequired

Total number of upvotes

Example: 42

Still need help? Ask the team