List & Read

List

GET /api/ext/comments

Returns a paginated list of your tasks, newest first.

Param	Type	Description
status	string	Comma-separated list of statuses to filter by — e.g. status=pending,submitted.
saved_account_id	string (UUID)	Restrict to a specific account.
page	integer	1-indexed page (default 1).
per_page	integer	1–100 (default 25).

curl -X GET "https://app.tokportal.com/api/ext/comments?status=manually_confirmed&per_page=50" \
  -H "X-API-Key: tok_live_xxx"

Response:

{
  "data": [
    {
      "id": "0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d",
      "status": "manually_confirmed",
      "platform": "tiktok",
      "saved_account_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
      "target_video_url": "https://www.tiktok.com/@someone/video/7000000000000000000",
      "target_author_handle": "someone",
      "comment_text": "Brilliant idea",
      "cm_payout_amount": 0.24,
      "submitted_at": "2026-04-27T17:21:34Z",
      "verified_at": null,
      "manually_confirmed_at": "2026-04-28T13:56:11Z",
      "client_dispute_deadline_at": "2026-05-01T13:56:11Z",
      "finalized_at": null,
      "correction_required": null,
      "deadline_at": "2026-04-30T17:21:00Z",
      "created_at": "2026-04-27T17:18:37Z",
      "updated_at": "2026-04-28T13:56:11Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 }
}

Read one

GET /api/ext/comments/{id}

Same task shape as in the list, wrapped under data.

curl -X GET https://app.tokportal.com/api/ext/comments/0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d \
  -H "X-API-Key: tok_live_xxx"

Returns 404 COMMENT_TASK_NOT_FOUND if the ID is unknown, 403 COMMENT_TASK_NOT_OWNED if it belongs to another user.

Cancel a pending task

DELETE /api/ext/comments/{id}

Refunds 1 credit and flips the task to cancelled. Only works while the task is still pending (the manager hasn't posted yet).

curl -X DELETE https://app.tokportal.com/api/ext/comments/0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d \
  -H "X-API-Key: tok_live_xxx"

Response:

{
  "data": {
    "id": "0d8b5a3e-92c4-4111-9a7d-3e2f1a2b3c4d",
    "status": "cancelled",
    "credits_refunded": 1
  }
}

If the manager has already moved the task past pending, you'll get a 409 COMMENT_INVALID_STATUS with the current status in details.current_status. From submitted onwards there is no cancellation — the workflow is already in flight.

Field reference

Field	Type	Description
id	string (UUID)	Task ID.
status	string	See the lifecycle for the full list.
platform	string	tiktok / instagram. Snapshot of the account's platform at create time.
saved_account_id	string (UUID)	The account posting the comment.
target_video_url	string	Canonicalized URL of the target video (tiktok.com/@x/video/..., instagram.com/reel/...).
target_author_handle	string | null	Parsed from the URL when available (TikTok /@handle/video/...).
comment_text	string	Exact text the manager posts.
cm_payout_amount	number	Manager's USD payout. 0.15 while pending; final value once verified_auto / finalized.
submitted_at	string | null	When the manager declared they posted.
verified_at	string | null	When auto-verification matched the comment.
manually_confirmed_at	string | null	When the manager manually confirmed (couldn't auto-verify).
client_dispute_deadline_at	string | null	UTC cutoff for you to dispute a manually_confirmed task. Auto-finalizes after that.
finalized_at	string | null	When the payout was locked.
correction_required	string | null	Human-readable instructions when the task is pending_corrections (your dispute reason or a verifier-detected mismatch).
deadline_at	string	Hard 72h deadline. Past this, pending tasks auto-cancel + refund.
created_at / updated_at	string	ISO 8601 timestamps.