> For the complete documentation index, see [llms.txt](https://docs.posynt.win/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.posynt.win/api-reference/overview.md).

# Overview

## Base URL

```
https://api.posynt.win/v1
```

## Format

* All responses are **JSON** (`Content-Type: application/json`).
* Timestamps are **ISO 8601 / UTC** (`2026-07-11T10:01:34Z`).
* Lists are paginated with a **cursor** (`next_cursor`).

## Endpoints

| Method   | Endpoint              | Description                                                                     |
| -------- | --------------------- | ------------------------------------------------------------------------------- |
| `GET`    | `/tracks`             | List your tracked hashtags                                                      |
| `POST`   | `/tracks`             | Add a hashtag                                                                   |
| `PATCH`  | `/tracks/{id}`        | Toggle `track_engagement` / `track_likes` / `track_reposts` / `track_comments`  |
| `DELETE` | `/tracks/{id}`        | Stop tracking a hashtag                                                         |
| `GET`    | `/accounts`           | List your tracked accounts                                                      |
| `POST`   | `/accounts`           | Track an X account                                                              |
| `PATCH`  | `/accounts/{id}`      | Toggle `track_engagement` / `track_likes` / `track_reposts` / `track_comments`  |
| `DELETE` | `/accounts/{id}`      | Stop tracking an account                                                        |
| `GET`    | `/posts`              | Fetch detected posts (and engagement events)                                    |
| `GET`    | `/notifications`      | Read your Discord/Telegram config                                               |
| `PUT`    | `/notifications`      | Update your Discord/Telegram config (Discord webhook count capped by plan)      |
| `POST`   | `/notifications/test` | Send a test alert to one channel                                                |
| `GET`    | `/usage`              | Current month's usage                                                           |
| `GET`    | `/me`                 | Your account, plan, and limits                                                  |
| `POST`   | `/me/resync-limits`   | Recompute your limits from your current plan (useful right after a plan change) |

## Pagination

```bash
curl "https://api.posynt.win/v1/posts?hashtag=ledroplive&limit=50&cursor=eyJ..." \
  -H "Authorization: Bearer psy_live_xxx"
```

If `next_cursor` is non-null, pass it as the `cursor` parameter for the next page.

## Plan limits

| Plan     | Hashtags | Accounts | Engagement-tracked sources | Discord webhooks | Scan frequency             | Alerts / month |
| -------- | -------- | -------- | -------------------------- | ---------------- | -------------------------- | -------------- |
| Starter  | 3        | 2        | 3                          | 1                | 1 min                      | 1,000          |
| Pro      | 15       | 10       | 15                         | 5                | real time (\~30s)          | 25,000         |
| Business | 40       | 25       | 25                         | 10               | priority real time (\~10s) | 75,000         |

`GET /v1/me` returns these as `hashtags_limit`, `accounts_limit`, `engagement_limit`, `webhooks_limit` and `alerts_limit` — always read them from there rather than hardcoding this table, since plan configs can change. Telegram is always a single channel (one bot/chat), on every plan — there's no count to cap.

Engagement tracking has its own, generally slower, refresh cadence (60s / 180s / 300s) since each refresh costs up to 3 X calls per tracked post.

A `POST`/`PATCH` that would exceed a plan limit (hashtags, accounts, engagement-tracked sources, or Discord webhooks on `PUT /notifications`) returns `403` with the code `plan_limit_reached` — it doesn't create a partial resource or silently truncate. Going over your **monthly alert quota** doesn't error at all: new posts simply stop being stored/delivered for the rest of the billing period (`GET /v1/usage` and `GET /v1/me` show where you stand) and resume once it resets.

## Rate limiting

Every `/v1` request counts against a per-API-key throughput cap, scaled by plan: **60/min** (Starter), **180/min** (Pro), **600/min** (Business). Each response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (unix seconds) so you can back off before hitting it. Going over returns `429` with `{"error": {"code": "rate_limited"}}`.

A handful of sensitive endpoints have their own, much tighter limits on top of that cap (also `429 rate_limited`, message includes the wait):

| Endpoint                                       | Limit           |
| ---------------------------------------------- | --------------- |
| `POST /2fa/enable`, `POST /2fa/disable`        | 6 / 5 min       |
| `POST /2fa/login`                              | 8 / 5 min       |
| `POST /notifications/test`                     | 10 / min        |
| `POST /apikey/regenerate`                      | 1 / 15 min      |
| `POST /api/checkout` (public, unauthenticated) | 20 / min per IP |

If you're building an integration, treat `429` as retriable with backoff — respect `X-RateLimit-Reset` (or the `wait` implied by the error message on the tighter endpoints) rather than retrying immediately.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.posynt.win/api-reference/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.