Public API

The Ankk Threads public API is available at https://threads-api.ankk.app/v1. It operates on accounts and content owned by the API-key user. Every account-specific request uses an explicit threads_account_id.

Authentication

Create a named API key in the web app. The raw key is displayed once. Send it as a bearer token:

Authorization: Bearer <api-key>

API keys inherit the owning user’s product entitlement and are subject to bounded request usage and rate limits. Never place a key in browser code, source control, or logs.

GET /v1/entitlement returns the current plan, status, purchased account capacity, and active-account usage. Read endpoints remain available after a trial or subscription ends; provider synchronization and all mutations fail closed until access is restored.

Safe mutations

Publish and delete requests require an Idempotency-Key header. Reusing the same key for the same operation returns its existing canonical job instead of starting a duplicate.

Idempotency-Key: <unique-operation-id>

An accepted asynchronous request reports whether dispatch was attempted, but acceptance is not the final Threads result. Read /v1/jobs/{job_id} until the canonical job reaches a terminal state.

Media uploads

POST /v1/uploads returns a short-lived signed R2 upload request. Upload the bytes directly to that URL, then call POST /v1/uploads/{upload_id}/verify. Only a verified upload ID can be attached to a content draft.

Listening

/v1/listening/references registers exact public Threads usernames under the API-key user. Collection jobs use one explicitly selected connected account and store profile/post results in PostgreSQL. /v1/listening/posts searches only those canonical collected results.

This is Threads Profile Discovery, not unrestricted network-wide keyword search. The collector needs threads_profile_discovery; Meta limits discovery to eligible public profiles and applies a rolling request quota. Deleting a reference deletes its collected posts. Disconnecting a collector stops new collection while preserving the user’s existing canonical history; deleting the owning user removes the dependent state. No cross-customer benchmark store is retained.

Analytics

/v1/analytics/accounts and /v1/analytics/posts return canonical metric snapshots for the API-key user’s own connected accounts. Collection requests are asynchronous and include an explicit UTC period plus an IANA timezone label. Account follower count is fetched separately because Meta does not allow since and until for that metric.

The OpenAPI document is the source of truth for request and response shapes. It intentionally omits encrypted credentials, Trigger task identifiers, raw provider responses, and internal user identifiers.