> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.siftsy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.siftsy.com/_mcp/server.

# Match links from your own data to posts

POST https://api.siftsy.app/analyst/v1/posts/match
Content-Type: application/json

Requires `posts:read`. Resolve up to 100 post links — from a
campaign tracker, a creator list, or a post-performance report — to
posts on this team. Each
input comes back once, in input order, with a `status`:

- `matched`: on the team and processed (`post` has the join keys and stored scores)
- `processing`: on the team, still syncing or scoring
- `failed`: on the team, processing failed
- `not_in_workspace`: a supported link the team has not added (or has archived)
- `invalid_url` / `unsupported_platform`: not a post link Siftsy analyzes

Query strings (tracking parameters), `www.`, `http` vs `https`, and
trailing slashes are ignored. Short links (`vm.tiktok.com`,
`youtu.be`) match only if that exact short link was added; send the
full post URL when you have it. `meta.matchedPostIds` feeds straight into
`selection.postIds` for `POST /posts/scan`, `POST /breakdowns`, or
`POST /analyses`. Nothing is added or charged; to add missing links
use `POST /content/posts/add`.

Rate class `posts_match` (20 / minute, 500 / day per key).


Reference: https://api.docs.siftsy.com/api-reference/siftsy-analyst-api/match-posts

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.
- `X-Api-Key` header (required) — API Key authentication via header

## Servers

- `https://api.siftsy.app/analyst/v1` (Production, default)
- `http://localhost:3000/analyst/v1` (Local development)

## Request

### Body (application/json)

This endpoint expects a MatchPostsRequest.

- `links` (list of string, required)

## Response

### 200

One row per input link

- `data` (list of PostMatch, optional)
- `meta` (EnvelopePostMatchesMeta, optional)

## Errors

### 400 Bad Request Error

Invalid request

- `any`

### 403 Forbidden Error

Missing required scope

- `any`

### 429 Too Many Requests Error

A per-minute cap, a per-day budget, or the daily transfer cap was exceeded. `error.message` is `Rate limit exceeded`, `Daily request limit exceeded`, or `Daily transfer limit exceeded`. Honor `Retry-After` (next UTC minute for burst caps; UTC midnight for daily budgets). Sized for a scheduled BI refresh: burst caps that a sequential loop cannot trip, daily budgets that fit eight full refreshes a day of a 500-post workspace or one full refresh plus hourly incrementals. Defaults: 300/minute and 10,000/day globally, with class budgets for per-post comment samples (120/min, 1,000/day), analysis-wide comment samples (20/min, 300/day), collection posts (60/min, 1,000/day), analysis reads (60/min, 2,000/day), analysis create (10/min, 100/day), AI search (2/min, 10/day), adding posts (10/min, 200/day), adding accounts (2/min, 20/day), refreshing posts (10/min, 200/day), and content job polls (60/min, 2,000/day). Daily transfer cap 500 MB.

- `any`

## Types

### PostMatch

- `input` (string, optional) — The link as sent
- `link` (string, optional, nullable) — The link as Siftsy read it
- `platform` (string, optional, nullable)
- `status` (enum, optional)
  - Allowed values: `matched`, `processing`, `failed`, `not_in_workspace`, `invalid_url`, `unsupported_platform`
- `postId` (string, optional, nullable)
- `post` (PostRow, optional, nullable) — A post with the keys analysts join on (`postId`, `link`, `platform`, `account`, `postedAt`, `collectionIds`, `tags`) and its stored scores and mix bars.

### EnvelopePostMatchesMeta

- `requested` (integer, optional)
- `counts` (map from string to integer, optional)
- `matchedPostIds` (list of string, optional)

### PostRow

A post with the keys analysts join on (`postId`, `link`, `platform`, `account`, `postedAt`, `collectionIds`, `tags`) and its stored scores and mix bars.

- `postId` (string, optional)
- `link` (string, optional, nullable)
- `platform` (string, optional, nullable)
- `account` (string, optional, nullable) — Creator handle, lowercase, without `@` (the same key as `by: account` breakdown groups)
- `accountName` (string, optional, nullable)
- `postedAt` (string, optional, nullable) — ISO-8601
- `title` (string, optional, nullable)
- `postType` (string, optional, nullable)
- `status` (string, optional, nullable)
- `tags` (list of string, optional)
- `collectionIds` (list of string, optional)
- `totalComments` (double, optional, nullable)
- `engagement` (RowEngagement, optional)
- `scores` (RowScores, optional) — Stored 1–10 scores for the team's selected score version.
- `mix` (MixSet, optional) — Every dimension is always present with all five buckets; buckets are `null` when unknown, so table columns never shift.

### RowEngagement

- `views` (double, optional, nullable)
- `likes` (double, optional, nullable)
- `comments` (double, optional, nullable)
- `shares` (double, optional, nullable)
- `saves` (double, optional, nullable)
- `engagementRate` (double, optional, nullable) — Percent. On post rows, computed from the counts when none is stored; on rollups, pooled over posts that report views.

### RowScores

Stored 1–10 scores for the team's selected score version.

- `siftsyScore` (double, optional, nullable)
- `sentiment` (double, optional, nullable)
- `relevance` (double, optional, nullable)
- `consensus` (double, optional, nullable)
- `content` (double, optional, nullable)
- `topic` (double, optional, nullable)

### MixSet

Every dimension is always present with all five buckets; buckets are `null` when unknown, so table columns never shift.

- `sentiment` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `relevance` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `consensus` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `content` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `topic` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.

### ScoreBuckets

Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.

- `positivePercent` (double, optional, nullable)
- `leanPositivePercent` (double, optional, nullable)
- `neutralPercent` (double, optional, nullable)
- `leanNegativePercent` (double, optional, nullable)
- `negativePercent` (double, optional, nullable)

## Examples

**Request**

```json
{
  "links": [
    "https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1",
    "https://www.instagram.com/p/C9xYzAbCdEf/"
  ]
}
```

**Response**

```json
{
  "data": [
    {
      "input": "string",
      "link": "string",
      "platform": "string",
      "status": "matched",
      "postId": "string",
      "post": {
        "postId": "string",
        "link": "string",
        "platform": "string",
        "account": "string",
        "accountName": "string",
        "postedAt": "string",
        "title": "string",
        "postType": "string",
        "status": "string",
        "tags": [
          "string"
        ],
        "collectionIds": [
          "string"
        ],
        "totalComments": 1.1,
        "engagement": {
          "views": 1.1,
          "likes": 1.1,
          "comments": 1.1,
          "shares": 1.1,
          "saves": 1.1,
          "engagementRate": 1.1
        },
        "scores": {
          "siftsyScore": 1.1,
          "sentiment": 1.1,
          "relevance": 1.1,
          "consensus": 1.1,
          "content": 1.1,
          "topic": 1.1
        },
        "mix": {
          "sentiment": {
            "positivePercent": 1.1,
            "leanPositivePercent": 1.1,
            "neutralPercent": 1.1,
            "leanNegativePercent": 1.1,
            "negativePercent": 1.1
          },
          "relevance": {
            "positivePercent": 1.1,
            "leanPositivePercent": 1.1,
            "neutralPercent": 1.1,
            "leanNegativePercent": 1.1,
            "negativePercent": 1.1
          },
          "consensus": {
            "positivePercent": 1.1,
            "leanPositivePercent": 1.1,
            "neutralPercent": 1.1,
            "leanNegativePercent": 1.1,
            "negativePercent": 1.1
          },
          "content": {
            "positivePercent": 1.1,
            "leanPositivePercent": 1.1,
            "neutralPercent": 1.1,
            "leanNegativePercent": 1.1,
            "negativePercent": 1.1
          },
          "topic": {
            "positivePercent": 1.1,
            "leanPositivePercent": 1.1,
            "neutralPercent": 1.1,
            "leanNegativePercent": 1.1,
            "negativePercent": 1.1
          }
        }
      }
    }
  ],
  "meta": {
    "requested": 1,
    "counts": {},
    "matchedPostIds": [
      "string"
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.siftsy.app/analyst/v1/posts/match"

payload = { "links": ["https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1", "https://www.instagram.com/p/C9xYzAbCdEf/"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.siftsy.app/analyst/v1/posts/match';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"links":["https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1","https://www.instagram.com/p/C9xYzAbCdEf/"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/posts/match"

	payload := strings.NewReader("{\n  \"links\": [\n    \"https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1\",\n    \"https://www.instagram.com/p/C9xYzAbCdEf/\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/posts/match")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"links\": [\n    \"https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1\",\n    \"https://www.instagram.com/p/C9xYzAbCdEf/\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/posts/match")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"links\": [\n    \"https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1\",\n    \"https://www.instagram.com/p/C9xYzAbCdEf/\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/posts/match', [
  'body' => '{
  "links": [
    "https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1",
    "https://www.instagram.com/p/C9xYzAbCdEf/"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/posts/match");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"links\": [\n    \"https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1\",\n    \"https://www.instagram.com/p/C9xYzAbCdEf/\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["links": ["https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1", "https://www.instagram.com/p/C9xYzAbCdEf/"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/posts/match")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```