# Video and tool directory submission protocol

## Account and authorization
1. The human signs in, verifies their email and creates a submission key at https://aitrendingvideo.com/settings/submission-keys.
2. Use Authorization: Bearer <dir_key> on authenticated API calls. Never send this key to another host. This key cannot access admin APIs.
3. Every submission or checkout POST requires a unique Idempotency-Key (8–128 ASCII letters, digits, dots, underscores, colons or hyphens). Reuse the same key and identical body when retrying. A pending/unknown response means inspect existing submissions, not issue another checkout.
4. Content-Type: application/json. Responses use {code:0,data:...}; failures use nonzero code and message. Respect 429 responses.

## Discover and avoid duplicates
GET https://aitrendingvideo.com/api/directory/categories
GET https://aitrendingvideo.com/api/directory/list?kind=tool&mode=directory&search=example
GET https://aitrendingvideo.com/api/directory/list?kind=video&mode=directory&search=example
GET https://aitrendingvideo.com/api/directory/detail?kind=video&slug=<slug>
Lists return {items,total}; page starts at 1 and pageSize is at most 100. Filters: search, category, platform, tag, pricing, capability. Platform values: tiktok,youtube,x,reels. News uses mode=news without kind.

## Submit
POST https://aitrendingvideo.com/api/directory/submissions
{
  "data": {
    "kind": "video",
    "url": "<full public HTTPS original video URL>",
    "title": "<factual title>",
    "description": "<factual introduction>",
    "category": "<category ID from categories>",
    "tags": ["<tag>"],
    "language": "en",
    "method": "ai",
    "toolIds": []
  }
}
Required fields: kind (video|tool), url, title (1–160 chars), description (1–5000 chars), category.
Optional: titleZh, descriptionZh, image (public HTTPS), tags (at most 10), language (en|zh|other), method (ai|hybrid|traditional), toolIds (published tool IDs, at most 10), pricing (free|freemium|paid), capabilities (generate|edit|captions|voice|effects). Platform is derived from the original URL. Unknown tool attribution must remain empty. Use full video URLs; shortened redirect links are not supported.
For tools, supply kind=tool and the tool website URL. Website TDK and AI suggestions are retained for the editor; failure permits manual review. Do not invent prices, view counts, engagement or tool attribution.
Response: {id,submissionId,slug,status:"pending"}. For a revision include entryId alongside data. Identity and owner cannot be changed. Published content stays live until its replacement is approved.

## Follow review
GET https://aitrendingvideo.com/api/directory/submissions — your revisions, review notes and website analysis.
GET https://aitrendingvideo.com/api/directory/entries — your entries and publication/payment status.
Videos can be submitted free and appear in News after approval. The video leaderboard requires a paid placement. One free tool listing requires BOTH an unused verified account allowance and an unused website allowance. Further tool listings require payment after approval.

## Placement purchase / top-up
POST https://aitrendingvideo.com/api/directory/checkout
{"entryId":"<your approved entry ID>","amountCents":100,"provider":"stripe","locale":"en"}
Providers: stripe or paypal, only when enabled. Minimum 100 integer USD cents, maximum 100000000. amountCents is the ADDITIONAL payment, not a target cumulative bid. Payment is validated and frozen server-side.
Response: {quoteId,checkout_url}. Present checkout_url to the human to complete payment. Do not collect payment credentials or claim a payment succeeded from a browser redirect.
A paid cycle lasts seven days. Top-ups during an active cycle increase its bid without extending its end. Payment after an expired cycle starts a new seven-day cycle. Only server-confirmed payment changes rank. Equal bids rank by when the current amount was reached.
GET https://aitrendingvideo.com/api/directory/bids — your quote/payment history. Confirm paid status here.
Keys cannot approve content, transfer ownership or refund. Moderation and payments follow the same rules for web and Agent submissions.