API Reference

Authentication

Use either a session cookie (dashboard) or an API key for server-to-server calls on /api/v1/tag. For unauthenticated trial calls, use /api/v1/tag_demo.

• API key: Set header x-api-key: YOUR_KEY or Authorization: Bearer YOUR_KEY
• Create and copy your key from the dashboard (key is shown once).

POST /api/v1/tag_demo

Anonymous trial endpoint for the landing-page experience. No auth required. Strictly limited to 10 requests/month/IP.

curl -X POST https://tag2me.app/api/v1/tag_demo \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/123"}'

Returns cached data when available or starts a workflow and returns videoId. Failed states include a user-safe message and optional errorCode.

POST /api/v1/tag

Authenticated endpoint for app users and API clients. Submit a video URL. If we have a cached result, we return it immediately. Otherwise we start an async job and return a videoId; poll GET /api/v1/tag?videoId=... until status is completed or failed.

curl -X POST https://tag2me.app/api/v1/tag \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://www.tiktok.com/@user/video/123"}'

Response (200): cached data.tags and data.description, or failed state with message and optional errorCode. Response (201): videoId — use it in GET to poll.

GET /api/v1/tag?videoId=...

Retrieve a tag result by the SHA-256 hash of the video URL (the videoId returned from POST). If processing fails, the response includes a user-safe message and optional errorCode.

curl -H "x-api-key: YOUR_API_KEY" \
  "https://tag2me.app/api/v1/tag?videoId=HASH_64_HEX"

GET /api/health

Health check; no auth. Returns status and dependency checks.

Errors & rate limits

400 (bad request), 401 (auth required), 404 (video not found), 429 (rate limit — check Retry-After header). All responses include X-Request-Id for support.