API reference
The public endpoints read public data only, need no key and work straight from a browser. Press Send a real request on them on this page. The Private API uses a creator's own personal key, reads only that owner's data, and is called from your own server or bot. Checked against the code and the live system on 28 Oct 2026.
In plain wordsAn API lets your program ask Tipjai for data by itself, for example to show a creator's name, picture and tip link on your site. What the public endpoints return is the same data anyone already sees on the web page. If you are a creator, you can make a personal key so your own bot reads your tips and totals, sends events to your alerts or controls your subathon timer.
Basics
- The base URL is
https://tipjai.comand every response is UTF-8 JSON, except the CSV file of/api/v1/me/export. - The public endpoints need no sign-up or key, and CORS is open to every origin (
Access-Control-Allow-Origin: *). The Private API needs a creator's personal key (see Keys and scopes) and sends no CORS headers. - The public endpoints have no payment details, no unpublished drafts and no tip-by-tip history. Amounts appear only when the creator chose to show totals.
- The Private API reads only the key owner's own data, with no PromptPay number, bank account or slips and nothing of any other creator's. It can write in only two ways: send events that are never money, and move the subathon clock.
- The Link API and Remote MCP have a full spec in OpenAPI 3.1. Stats, creator, leaderboard, market and the Private API are described on this page; the OpenAPI document has no entries for the Private API.
Keys and scopes
- The Private API endpoints use a creator's personal API key. Every request carries it in this header:
Authorization: Bearer tj_live_.... A key starts withtj_live_and is free on every plan. A key can do only what the scopes picked when it was made allow. - Create a key in Studio (
studio.tipjai.com/api): open the Free tools group (เครื่องมือฟรี), choose API and webhooks (API และ Webhooks), and on the Personal API keys card (คีย์ API ส่วนตัว) name the key (ชื่อคีย์, up to 60 characters), tick the scopes it needs and press Create key (สร้างคีย์). The Connections and notifications page (เชื่อมต่อและแจ้งเตือน) links there too, from its card API keys and the developer guide (คีย์ API และคู่มือนักพัฒนา). - Studio shows the whole key once, right after it is created, marked (แสดงครั้งเดียว) (shown once). Copy it then. Tipjai keeps only a hash of the key, so it can never show it again. If you lose it, revoke it and make a new one.
- You can have up to 10 live keys. The list คีย์ของคุณ (Your keys) shows each key's name, its first characters, its scopes, when it was created and when it was last used (ใช้ล่าสุด, or ยังไม่เคยใช้ for never). Revoke (ยกเลิกคีย์) works at once and is final: every tool using that key stops working, and the key cannot be turned back on. Make a new one if you still need it.
- Creating a key needs a recent sign-in. If yours is not recent, Studio asks you to sign in again and keeps what you typed. If two-step sign-in is on, you also enter a fresh 6-digit code from your authenticator app.
- Use a key only from your own server or bot. Keep it in an environment variable or a secret store, and never put it in a web page or in code others can see. The Private API sends no CORS headers, so it is not meant to be called from a web page, and this page has no live request button for it. If a key leaks, revoke it and make a new one.
- Only the money Studio's income page counts: confirmed tips that are not tests (verification is verified, structural or creator_confirmed). Days are Bangkok days. An event you send in is not a tip, so it never appears.
- A key reads only its owner's own data, including the supporter names and messages on that creator's own tips. It can write in only two ways: send events that are never money, and move the subathon clock. It cannot move money, confirm or change tips, change payment destinations, or read any other creator's private data. Access today is by a creator's own personal key only.
The five scopes
| Scope | As Studio's card words it | Used by |
|---|---|---|
tips:read | Read confirmed tips | GET /me/tips, tipjai_my_tips |
stats:read | Read daily totals | GET /me/stats, tipjai_my_stats |
export:read | Download the income statement as CSV | GET /me/export |
events:write | Send other platforms' events to your alerts (never counted as money) | POST /me/events |
timer:write | Control the subathon timer: add, subtract, pause, resume | POST /me/timer, tipjai_timer_control |
GET /api/v1/me works with any working key and needs no scope. The tipjai_* names are Remote MCP tools when you send a key; see Remote MCP.
Errors and rate limits
- Errors from the public endpoints come back as
{"error":"…"}with an HTTP status such as404429503 - The creator, market, stats and validate endpoints allow 60 requests a minute per IP. Above that you get
429withRetry-Afterand that response is never cached. - The Link API catalogs (templates, platforms, schema, knowledge) are static, cached at the CDN for 5 minutes and not rate limited.
503means the data is briefly unavailable. Try again afterRetry-Afterwhen it is sent.- The Private API answers errors as
{"error":"…","message":"…"}Use error in your code; message is English text for people. Every JSON answer carriesCache-Control: no-storeandVary: Authorization(the CSV file carries only Cache-Control: no-store), and a 401 also carriesWWW-Authenticate: Bearer realm="tipjai" - The Private API counts 120 requests a minute per key, across every endpoint and across every MCP request sent with the key. Above that you get 429 with Retry-After. On top of that, per creator however many keys are used: export 10 files a minute, events 60 events a minute, timer 30 commands a minute (REST and MCP together).
Answers for a missing, wrong or short-of-scope key
401 {"error":"missing_api_key","message":"Send your key as Authorization: Bearer tj_live_..."}
401 {"error":"invalid_api_key","message":"This key is not valid, or it was revoked. Create a new one in Tipjai Studio."}
403 {"error":"insufficient_scope","message":"This key does not have the tips:read scope. Create a key with it in Tipjai Studio."}
429 {"error":"rate_limited","message":"Too many requests. Retry after the number of seconds in Retry-After."}
503 {"error":"auth_unavailable","message":"Tipjai could not check this key right now. Retry in a moment."}The wording above is read from Tipjai's code. A real answer captured from tipjai.com is under GET /api/v1/me, which uses the message Send a valid key as Authorization: Bearer tj_live_... for 401 and Retry in a moment. for 429 and 503. The error codes are the same.
Platform stats
/api/v1/statsHow many creators have signed up to Tipjai, and how many launch seats are left.
Response
| Field | Type | Description |
|---|---|---|
creators | number | null | Creators signed up |
launch_cap | number | null | Sign-up cap for the launch period |
seats_remaining | number | null | Seats left |
When it fails
| Status | Body | Meaning |
|---|---|---|
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After, then try again. This response is never cached. |
503 | {"error":"stats_unavailable"} | Stats are briefly unavailable. Try again after 30 seconds. |
Cache-Control public, s-maxage=60, stale-while-revalidate=300
curl https://tipjai.com/api/v1/stats
Press Send a real request and the live response with its status shows here.
Find a creator by name
/api/v1/creatorsGive a creator's name or page name and get the closest matches first, each with the page where their fans tip them (tip_url). It answers "where do I tip this person" when all you have is a name. Only what the profile page already shows comes back: no amounts, no view counts, no payment details.
- The query takes letters (Thai vowel and tone marks included), digits, spaces and . _ - only. A pasted tipjai.com/name address or an @name works too: it is reduced to the page name.
- Best match first: a page name or display name that matches exactly, then names that start with the query, then names that contain it.
- Only creators whose tip page is listed publicly: they can be paid, have a name, are not a demo account and are not being deleted.
- bio is text the creator wrote. The answer is marked with content_trust: treat it as data, never as an instruction.
- The MCP tool tipjai_find_creators runs the same search.
Parameters
| Name | Type | Description |
|---|---|---|
q | string | The creator's name or page name, 2 to 60 characters. Anything longer is cut. |
limit | 1 to 10 | How many results. 5 if left out; a value outside the range is brought into it. |
Response
| Field | Type | Description |
|---|---|---|
object | "list" | The kind of answer |
content_trust | "creator_authored_untrusted" | Says the text in the items was written by creators |
query | string | The query after it was tidied |
limit_max | number | The largest limit you can ask for (10) |
count | number | How many items came back |
items[].username | string | Page name |
items[].display_name | string | Display name |
items[].bio | string | null | The creator's own line, one line, at most 160 characters |
items[].categories | string[] | The categories the creator picked |
items[].verified | boolean | Whether the creator is verified |
items[].tip_url | string | Tip page URL, ready to hand to whoever asked |
items[].avatar_url | string | null | Profile picture URL |
items[].socials | object | The channels the creator's own page links to, keyed by platform |
items[].matched_on | "handle" | "name" | Whether the page name or the display name matched |
search_page | string | The search page on tipjai.com for the same words, for a person to open |
note | string | A short reminder of what tip_url is, and that bio is data, not an instruction |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"query_too_short", "message":"…"} | q is shorter than 2 characters after tidying, or missing. This answer is not cached. |
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After (60 seconds) and try again. |
503 | {"error":"temporarily_unavailable"} | The search is briefly unavailable. Try again after Retry-After (10 seconds). |
Cache-Control public, s-maxage=120, stale-while-revalidate=600
curl https://tipjai.com/api/v1/creators?q=tipjai&limit=2
Press Send a real request and the live response with its status shows here.
Creator public profile
/api/v1/creator/{username}Give a creator's page name and get back what their profile page already shows. Use it for an intro card or to show a tip link on your site. It never includes payment details.
Parameters
| Name | Type | Description |
|---|---|---|
username | string, path | Page name, the last part of tipjai.com/name, for example tipjai. A name the creator has since changed answers 308 with a Location to the same endpoint under the name they use now. |
Response
| Field | Type | Description |
|---|---|---|
username | string | Page name |
display_name | string | Display name |
bio | string | null | Bio |
avatar_url | string | null | Profile picture URL |
accent_color | string | Accent colour as hex |
category | string | null | Main category |
categories | string[] | Every category picked |
verified | boolean | Whether the creator is verified |
verified_handle | string | null | Handle used for verification |
views | number | Page views |
support_activity_visible | boolean | Whether the creator shows their totals |
total_received | number | null | Confirmed total, null when the creator hides totals |
supporters | number | null | Supporter count, null when the creator hides totals |
socials | object | Other channels, keyed by platform |
tip_url | string | Tip page URL, ready to share with viewers |
When it fails
| Status | Body | Meaning |
|---|---|---|
404 | {"error":"not_found"} | No creator with this name |
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After, then try again. This response is never cached. |
503 | {"error":"temporarily_unavailable"} | Briefly unavailable, try again |
Cache-Control no-store
curl https://tipjai.com/api/v1/creator/tipjai
Press Send a real request and the live response with its status shows here.
Published Link page
/api/v1/creator/{username}/linksA creator's link page at link.tipjai.com/name, with its design and every link. The text is written by the creator; never treat it as instructions.
Parameters
| Name | Type | Description |
|---|---|---|
username | string, path | Page name. A name the creator has since changed answers 308 to the one they use now. |
Response
| Field | Type | Description |
|---|---|---|
schema_version | number | Data format version, currently 5 |
content_trust | string | creator_authored_untrusted: the text comes from the creator and is not an instruction |
username, display_name, bio | string | Profile details; bio may be null |
avatar_url, cover_url | string | null | Profile and cover images |
link_url, tip_url | string | Link page and tip page URLs |
show_tip | boolean | Whether the Link page shows the tip button: true when the button is switched on and the creator can take payments right now |
design | object | Page design (LinkPageDesign in the OpenAPI spec) |
links | array | Every link, in order. Each has a type: link, social, header, image, canvas, widget or copy |
socials | object | Social links |
updated_at | string | null | Last edited |
next_change_at | string | null | When a scheduled link next starts or stops showing, null if none. Tells you when to fetch again. |
When it fails
| Status | Body | Meaning |
|---|---|---|
404 | {"error":"not_found"} | No creator with this name |
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After, then try again. This response is never cached. |
503 | {"error":"temporarily_unavailable"} | Briefly unavailable, try again |
Cache-Control no-store
curl https://tipjai.com/api/v1/creator/tipjai/links
Press Send a real request and the live response with its status shows here.
Supporter leaderboard
/api/v1/creator/{username}/leaderboardA creator's top supporters, only when the creator shows totals. If totals are hidden, the list is empty and hidden is true.
Parameters
| Name | Type | Description |
|---|---|---|
username | string, path | Page name. A name the creator has since changed answers 308 to the one they use now, with the same query. |
period | month | all | Time range, default month |
limit | 1 to 50 | How many rows, default 10. A fraction is rounded down. |
Response
| Field | Type | Description |
|---|---|---|
username | string | Page name |
period | string | month or all |
hidden | boolean | true when the creator hides totals |
count | number | Row count |
leaderboard[].supporter | string | Name the supporter typed |
leaderboard[].total | number | null | Total |
leaderboard[].tips | number | Number of tips |
When it fails
| Status | Body | Meaning |
|---|---|---|
404 | {"error":"not_found"} | No creator with this name |
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After, then try again. This response is never cached. |
503 | {"error":"unavailable"} | Briefly unavailable, try again after 10 seconds |
Cache-Control no-store
curl https://tipjai.com/api/v1/creator/tipjai/leaderboard?period=month&limit=10
Press Send a real request and the live response with its status shows here.
Creator market
/api/v1/marketProfile frames and products creators sell in the Tipjai market. Free frames are always listed; a paid frame or a product is listed only when its seller can take the buyer's money at checkout right now, the same rule as the market page on tipjai.com.
Response
| Field | Type | Description |
|---|---|---|
count, frames[] | number, array | Frames: id, title, kind, colors, price, free, acquired, seller |
product_count, products[] | number, array | Products: id, title, description, image, price, currency, product_type, fulfillment_type, fulfillment_eta_days, sold, seller |
total_count | number | Frames plus products |
When it fails
| Status | Body | Meaning |
|---|---|---|
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After, then try again. This response is never cached. |
503 | {"error":"unavailable"} | The listing or its sellers could not be read. Try again after 10 seconds. This response is never cached. |
Cache-Control public, s-maxage=60, stale-while-revalidate=300
curl https://tipjai.com/api/v1/market
Press Send a real request and the live response with its status shows here.
Link page templates
/api/v1/link/templatesAll 20 Link page design templates, with Thai and English names.
Parameters
| Name | Type | Description |
|---|---|---|
limit | 1 to 50 | Default 20 |
offset | 0 or more | Default 0 |
Response
| Field | Type | Description |
|---|---|---|
schema_version | number | 5 |
total, count, offset | number | Paging counters |
has_more, next_offset | boolean, number | null | Whether there is a next page, and where it starts |
items[] | array | id, name_th, name_en, description_th, description_en, mood, design |
Cache-Control public, s-maxage=300, stale-while-revalidate=3600
curl https://tipjai.com/api/v1/link/templates?limit=2
Press Send a real request and the live response with its status shows here.
Known platforms
/api/v1/link/platformsThe platforms a Link page knows, with their base URLs.
Parameters
| Name | Type | Description |
|---|---|---|
limit | 1 to 50 | Default 20 |
offset | 0 or more | Default 0 |
Response
| Field | Type | Description |
|---|---|---|
schema_version | number | 5 |
total, count, offset, has_more, next_offset | number, boolean | Paging counters; there are 19 platforms now |
items[] | array | key, label, icon_key, base_url, placeholder |
Cache-Control public, s-maxage=300, stale-while-revalidate=3600
curl https://tipjai.com/api/v1/link/platforms?limit=3
Press Send a real request and the live response with its status shows here.
Cited playbooks
/api/v1/link/knowledgeAdvice for creators from a reviewed library. The same question always gets the same answer; it never searches the live web and holds no creator account data.
Parameters
| Name | Type | Description |
|---|---|---|
prompt | string, up to 500 | The question |
category | string | Repeat it or separate with commas, up to 3 |
platform | string | Repeat it or separate with commas, up to 12 |
topic | enum | tipjai-boundaries, link-architecture, accessibility, youtube, line, creator-playbook |
limit | 1 to 12 | Default 6 |
Response
| Field | Type | Description |
|---|---|---|
schema_version, knowledge_version | number, string | Versions of the data format and of the library |
count, items[] | number, array | Advice with its sources |
Cache-Control public, s-maxage=300, stale-while-revalidate=3600
curl https://tipjai.com/api/v1/link/knowledge?topic=link-architecture&limit=2
Press Send a real request and the live response with its status shows here.
JSON Schema
/api/v1/link/schemaSchemas for a Link page draft and for what comes back after validation. Use them to check your data before you send it. Version 5 adds the copy block (a line of text a visitor copies); version 4 added identity tokens and widgets that load only after the visitor agrees.
Response
| Field | Type | Description |
|---|---|---|
schema_version | number | 5 |
draft_input | JSON Schema | The draft shape validate accepts |
design_output, link_output | JSON Schema | The shapes you get back |
Cache-Control public, s-maxage=300, stale-while-revalidate=3600
curl https://tipjai.com/api/v1/link/schema
Press Send a real request and the live response with its status shows here.
Validate a Link page draft
/api/v1/link/validateSend a draft and get back a normalised draft with a list of problems. It only checks: it cannot save, publish, delete or touch payment settings.
Parameters
| Name | Type | Description |
|---|---|---|
body | application/json, up to 128 KB | links (required, up to 40) and design. Each link has a type: link, social, header, image, canvas, widget or copy |
links[] (type "copy") | object | A block of text a visitor copies in one tap. It needs a label and copy_text (one line of plain text, up to 120 characters, no ://; use an ordinary link for a web address). icon is a platform key or null. Up to 6 a page. Over 120 characters, or no label or copy_text, answers 400 invalid_draft with the position. Text with :// gets invalid_copy, and a 7th block gets copy_limit. Example: {"type":"copy","label":"LINE ID","copy_text":"@tipjai"} |
Response
| Field | Type | Description |
|---|---|---|
schema_version | number | 5 |
valid | boolean | Whether everything passed |
design, links | object, array | The normalised draft |
issues, warnings | array | Problems to fix, each with an index and one of 11 codes: invalid_url, invalid_media, invalid_canvas, invalid_widget, invalid_copy, missing_label, limit, media_limit, canvas_limit, widget_limit, copy_limit. Warnings carry multiple_highlights_normalized. |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"invalid_draft", …} | Malformed, with issues that point to where |
413 | too large | Body over 128 KB |
415 | wrong type | Content-Type must be application/json |
429 | {"error":"rate_limited"} | More than 60 requests a minute from one IP. Wait for Retry-After, then try again. This response is never cached. |
Cache-Control no-store
curl -X POST https://tipjai.com/api/v1/link/validate \
-H "Content-Type: application/json" \
-d '{"links":[{"type":"link","label":"YouTube channel","url":"https://youtube.com/@tipjai"}]}'Press Send a real request and the live response with its status shows here.
Who this key belongs to
/api/v1/meScope needed none, any working key can call it
Asks which creator a key belongs to and what it may do. Any working key can call it, with no extra scope. Use it to check that a key is set up right before you call the others.
Response
| Field | Type | Description |
|---|---|---|
creator.username, creator.display_name | string | The key owner's page name and display name |
key.id | string (uuid) | This key's id, not the key itself |
key.scopes | string[] | The scopes this key has, such as tips:read |
When it fails
| Status | Body | Meaning |
|---|---|---|
401 | {"error":"missing_api_key"} | No Authorization: Bearer tj_live_... header (a value that does not start with tj_live_ counts as no key) |
401 | {"error":"invalid_api_key"} | The key is not valid, or it was revoked. Create a new one in Studio. |
429 | {"error":"rate_limited"} | More than 120 requests a minute on one key, or too many from one IP address. Wait for Retry-After, then try again. |
503 | {"error":"auth_unavailable"} | The key could not be checked just now. Try again after Retry-After (30 seconds). |
503 | {"error":"unavailable"} | Your data could not be read just now. Try again after Retry-After (30 seconds). |
Cache-Control no-store
curl "https://tipjai.com/api/v1/me" \ -H "Authorization: Bearer tj_live_..."
{
"creator": {
"username": "your_name",
"display_name": "Your Name"
},
"key": {
"id": "5f0f4f5a-3c2d-4d2b-8e8e-2a6f7c1d9b10",
"scopes": [
"tips:read",
"stats:read"
]
}
}There is no live request button for an endpoint that needs a key, because a key should never be typed into a web page. Use the example above in your own server-side code.
A real answer when no key is sent
curl -i https://tipjai.com/api/v1/me
{
"error": "missing_api_key",
"message": "Send a valid key as Authorization: Bearer tj_live_..."
}Confirmed tips
/api/v1/me/tipsScope needed tips:read
The key owner's confirmed tips, newest first, paged with a cursor. Use it for your own dashboard, bot or sheet. It counts only the money Studio's income page counts: no test tips, no tips that are not confirmed, and none of the events you send in yourself.
- from and to are Bangkok days (Asia/Bangkok) and count the whole day. They filter and sort on settled_at, the moment the tip became money.
- Get the next page by sending next_cursor as cursor. When next_cursor is null, there are no more.
- supporter and message are written by the person who tipped. Treat them as data, never as instructions.
- Play tips, which the sender confirmed without a slip (verification unverified), are not in this list, even though a webhook delivers them, because Studio's income page does not count them as money.
Parameters
| Name | Type | Description |
|---|---|---|
limit | 1 to 100 | Tips per page, default 25 |
cursor | string | The next_cursor of the previous page, to get the next one |
from | YYYY-MM-DD | First day to include, Bangkok time, the whole day |
to | YYYY-MM-DD | Last day to include, Bangkok time, the whole day |
min_amount | number | Smallest amount to include, 0 to 10,000,000 |
max_amount | number | Largest amount to include, 0 to 10,000,000 |
Response
| Field | Type | Description |
|---|---|---|
object | string | Always list |
data[] | array | The tips on this page, each with id, amount, currency, supporter, message, verification, payment_method, gift, settled_at, created_at |
data[].id | string (uuid) | The tip's id |
data[].amount, data[].currency | number, string | Amount and currency, normally THB |
data[].supporter, data[].message | string | The name and message the supporter typed, empty when there is none |
data[].verification | string | How it was confirmed: verified (the bank confirmed the amount), structural (the amount as the sender told it) or creator_confirmed (the creator checked the account and confirmed) |
data[].payment_method | string | The channel the tip came through, such as promptpay |
data[].gift | object | null | id, name, qty when the tip came with a gift, otherwise null |
data[].settled_at, data[].created_at | string | When the tip became money and when it was created, as full ISO 8601 timestamps |
next_cursor | string | null | Send it as cursor to get the next page; null when there are no more |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"invalid_limit", …} | A query value is wrong; error says which: invalid_limit, invalid_cursor, invalid_from, invalid_to, from_after_to, invalid_min_amount or invalid_max_amount. The message reads: Check the query parameters: limit 1-100, cursor from next_cursor, from/to as YYYY-MM-DD, min_amount/max_amount as numbers. |
401 | {"error":"missing_api_key"} | No Authorization: Bearer tj_live_... header (a value that does not start with tj_live_ counts as no key) |
401 | {"error":"invalid_api_key"} | The key is not valid, or it was revoked. Create a new one in Studio. |
403 | {"error":"insufficient_scope"} | This key does not have the tips:read scope. Create a key with it in Studio. |
429 | {"error":"rate_limited"} | More than 120 requests a minute on one key, or too many from one IP address. Wait for Retry-After, then try again. |
503 | {"error":"auth_unavailable"} | The key could not be checked just now. Try again after Retry-After (30 seconds). |
503 | {"error":"unavailable"} | Your data could not be read just now. Try again after Retry-After (30 seconds). |
Cache-Control no-store
curl "https://tipjai.com/api/v1/me/tips?limit=2" \ -H "Authorization: Bearer tj_live_..."
{
"object": "list",
"data": [
{
"id": "2d7c1d0e-6a5b-4a38-9f60-1c3b8e4a7d12",
"amount": 100,
"currency": "THB",
"supporter": "มะลิ",
"message": "สู้ ๆ",
"verification": "verified",
"payment_method": "promptpay",
"gift": null,
"settled_at": "2026-10-21T13:00:00.123456+00:00",
"created_at": "2026-10-21T12:59:41.502113+00:00"
},
{
"id": "9a4e6b21-0f3c-4d57-a1b8-7e2d5c9f3a60",
"amount": 30,
"currency": "THB",
"supporter": "ต้นไม้",
"message": "ขอบคุณครับ",
"verification": "creator_confirmed",
"payment_method": "promptpay",
"gift": { "id": "rose", "name": "กุหลาบ", "qty": 3 },
"settled_at": "2026-10-21T11:42:10.804512+00:00",
"created_at": "2026-10-21T11:41:55.017834+00:00"
}
],
"next_cursor": "MjAyNi0xMC0yMVQxMTo0MjoxMC44MDQ1MTIrMDA6MDB8OWE0ZTZiMjEtMGYzYy00ZDU3LWExYjgtN2UyZDVjOWYzYTYw"
}There is no live request button for an endpoint that needs a key, because a key should never be typed into a web page. Use the example above in your own server-side code.
Daily totals
/api/v1/me/statsScope needed stats:read
Totals of confirmed tips by day (Bangkok time), with the sum for the whole range. Good for a chart or a monthly summary. It uses the same money rule as Studio's income page.
Parameters
| Name | Type | Description |
|---|---|---|
from | YYYY-MM-DD | First day to include, Bangkok time. If left out, it starts 29 days before the last day (30 days in all). |
to | YYYY-MM-DD | Last day to include, Bangkok time. If left out, today. The range between from and to can be at most 366 days. |
Response
| Field | Type | Description |
|---|---|---|
from, to, time_zone, currency | string | The range asked for (Bangkok days), the time zone Asia/Bangkok and the currency THB |
totals | object | Sums for the whole range: tips (how many), total, and verified_total, structural_total and creator_confirmed_total (split by how the tip was confirmed) |
days[] | array | Each day with money, oldest first. Days without money are left out. |
days[].date | string | The day as YYYY-MM-DD, Bangkok time |
days[].tips, days[].supporters | number | How many tips, and how many different supporter names that day. Tips with no name are not counted as names. |
days[].total, days[].verified_total, days[].structural_total, days[].creator_confirmed_total | number | The day's total, and the totals split by how the tips were confirmed |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"invalid_from", …} | A date is wrong; error says which: invalid_from, invalid_to, from_after_to (from is after to) or range_too_long (over 366 days). The message text is English. |
401 | {"error":"missing_api_key"} | No Authorization: Bearer tj_live_... header (a value that does not start with tj_live_ counts as no key) |
401 | {"error":"invalid_api_key"} | The key is not valid, or it was revoked. Create a new one in Studio. |
403 | {"error":"insufficient_scope"} | This key does not have the stats:read scope. Create a key with it in Studio. |
429 | {"error":"rate_limited"} | More than 120 requests a minute on one key, or too many from one IP address. Wait for Retry-After, then try again. |
503 | {"error":"auth_unavailable"} | The key could not be checked just now. Try again after Retry-After (30 seconds). |
503 | {"error":"unavailable"} | Your data could not be read just now. Try again after Retry-After (30 seconds). |
Cache-Control no-store
curl "https://tipjai.com/api/v1/me/stats?from=2026-10-01&to=2026-10-21" \ -H "Authorization: Bearer tj_live_..."
{
"from": "2026-10-01",
"to": "2026-10-21",
"time_zone": "Asia/Bangkok",
"currency": "THB",
"totals": {
"tips": 3,
"total": 180,
"verified_total": 150,
"structural_total": 0,
"creator_confirmed_total": 30
},
"days": [
{
"date": "2026-10-20",
"tips": 1,
"supporters": 1,
"total": 50,
"verified_total": 50,
"structural_total": 0,
"creator_confirmed_total": 0
},
{
"date": "2026-10-21",
"tips": 2,
"supporters": 2,
"total": 130,
"verified_total": 100,
"structural_total": 0,
"creator_confirmed_total": 30
}
]
}There is no live request button for an endpoint that needs a key, because a key should never be typed into a web page. Use the example above in your own server-side code.
Income statement (CSV)
/api/v1/me/exportScope needed export:read
The income statement as a CSV file: the same columns and note lines as the CSV download buttons on Studio's Tips page (ทิป). Good for bookkeeping tools or a sheet of your own. The answer is a CSV file, not JSON.
- The file is UTF-8 with a BOM, then 4 note lines that start with #, then the header row. A range with no tips returns the note lines only.
- The response headers name the file in Content-Disposition (tipjai-statement-first-day-to-last-day.csv) and give the row count in X-Tipjai-Rows.
- At most 20,000 rows a file. More than that answers 422 range_too_large: ask for a shorter range.
- Text that starts with =, +, - or @ gets a ' in front, so a spreadsheet never runs it as a formula.
Parameters
| Name | Type | Description |
|---|---|---|
from | YYYY-MM-DD | First day to include, Bangkok time. If left out, it starts 29 days before the last day (30 days in all). |
to | YYYY-MM-DD | Last day to include, Bangkok time. If left out, today. The range between from and to can be at most 366 days. |
Columns in the file
| Column | Type | Description |
|---|---|---|
วันที่ | text | The date as YYYY-MM-DD, Bangkok time |
เดือน | number | Month number, 1 to 12 |
ปี_พศ | number | Year in the Buddhist era |
ปี_คศ | number | Year in the Gregorian calendar |
ผู้สนับสนุน | text | The name the supporter typed |
ยอดรับ_บาท | number | Amount received |
ค่าธรรมเนียมแพลตฟอร์ม_บาท | number | Always 0: Tipjai takes no fee on tips |
ค่าธรรมเนียมผู้ให้บริการชำระเงิน_บาท | number, blank | 0, or blank when the tip came by card: the card payment provider takes its own fee and Tipjai does not know it |
สุทธิ_บาท | number, blank | Net amount, blank for card tips |
ช่องทาง | text | The channel the tip came through, such as promptpay |
การยืนยัน | text | verified, structural or creator_confirmed |
ยอดยืนยันกับธนาคาร | text | ใช่ (yes) when the bank confirmed the amount; otherwise text saying the amount is as the sender told it, or that the creator checked the account and confirmed |
ข้อความ | text | The sender's message |
ของขวัญ | text | The gift's name, blank when there is none |
รางวัลที่สัญญา | text | What the creator promised with that gift, blank when there is none |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"invalid_from", …} | A date is wrong; error says which: invalid_from, invalid_to, from_after_to (from is after to) or range_too_long (over 366 days). The message text is English. |
422 | {"error":"range_too_large"} | More than 20,000 tips in this range. Ask for a shorter range. |
401 | {"error":"missing_api_key"} | No Authorization: Bearer tj_live_... header (a value that does not start with tj_live_ counts as no key) |
401 | {"error":"invalid_api_key"} | The key is not valid, or it was revoked. Create a new one in Studio. |
403 | {"error":"insufficient_scope"} | This key does not have the export:read scope. Create a key with it in Studio. |
429 | {"error":"rate_limited"} | More than 120 requests a minute on one key, too many from one IP address, or more than 10 files a minute for one creator. Wait for Retry-After, then try again. |
503 | {"error":"auth_unavailable"} | The key could not be checked just now. Try again after Retry-After (30 seconds). |
503 | {"error":"unavailable"} | Your data could not be read just now. Try again after Retry-After (30 seconds). |
Cache-Control no-store
curl "https://tipjai.com/api/v1/me/export?from=2026-10-01&to=2026-10-21" \ -H "Authorization: Bearer tj_live_..." \ -o tipjai-statement.csv
# สรุปรายรับจาก Tipjai ซึ่งไม่หักค่าธรรมเนียม (เงินโอนตรงจากผู้ให้ทิปถึงคุณ) # … (3 more note lines, each starting with #) วันที่,เดือน,ปี_พศ,ปี_คศ,ผู้สนับสนุน,ยอดรับ_บาท,ค่าธรรมเนียมแพลตฟอร์ม_บาท,ค่าธรรมเนียมผู้ให้บริการชำระเงิน_บาท,สุทธิ_บาท,ช่องทาง,การยืนยัน,ยอดยืนยันกับธนาคาร,ข้อความ,ของขวัญ,รางวัลที่สัญญา 2026-10-21,10,2569,2026,มะลิ,100,0,0,100,promptpay,verified,ใช่,สู้ ๆ,, 2026-10-21,10,2569,2026,ต้นไม้,30,0,0,30,promptpay,creator_confirmed,ไม่ (ครีเอเตอร์ตรวจบัญชีและยืนยัน),ขอบคุณครับ,กุหลาบ, 2026-10-20,10,2569,2026,ฟ้า,50,0,0,50,promptpay,verified,ใช่,เป็นกำลังใจให้,,
There is no live request button for an endpoint that needs a key, because a key should never be typed into a web page. Use the example above in your own server-side code.
Send an event to your alerts
/api/v1/me/eventsScope needed events:write
Let your own tool send another platform's events, such as a YouTube gift or a Kick follow, to the same alert box as tips. An event is never money and never counts toward any total.
- It uses the same switches as TikTok alerts, in the TikTok LIVE alerts section (แจ้งเตือนจาก TikTok LIVE) of Overlay Studio (the page is named แจ้งเตือนและวิดเจ็ต in Thai). Show TikTok alerts on this overlay must be ticked (it is on to start with). To send follows or shares, Show new followers (แสดงคนกดติดตาม) or Show shares (แสดงคนแชร์ไลฟ์) must be ticked too; both are off to start with.
- An event is never money: never in totals, goals, rankings, the subathon clock, income, tax or webhooks. A body with a field named amount, value, price, currency, diamonds, coins, baht, total or money (at the top or inside gift) is refused with 422.
- The first call answers 201. A retry with the same Idempotency-Key within 7 days answers 200 with the first result and the header Idempotent-Replayed: true, and never shows twice. If the first call is still running, a retry gets 409; if it stopped before it stored a result, a retry after about a minute shows the event once.
- The creator's word filter (ตัวกรองคำหยาบ) also applies to the name on the card, and filtered words are masked.
Parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Key | header, required | 1 to 120 characters of A-Z a-z 0-9 _ . : -, for example the event's own id on its platform |
body | application/json, up to 4 KB | One JSON object: type, name, source (optional), gift (gift events only). An unknown field is refused. |
type | enum | The kind of event: gift, follow, share or sub |
name | string | The viewer's name on the card, up to 40 characters; the rest is cut off |
source | string | Optional short label for where it came from, such as YouTube, up to 24 characters, shown under the card |
gift | object | Required when type is gift: gift.name, up to 32 characters, and gift.count, a whole number from 1 to 99,999 (1 if left out). The other types must not send gift. |
Response
| Field | Type | Description |
|---|---|---|
id | string (uuid) | The id of the event Tipjai accepted |
object | string | Always event |
type | string | gift, follow, share or sub, as sent |
shown | boolean | true once it was sent to your alert screen |
reason | string | null | null when shown is true. Otherwise it says why: platform_alerts_off (alerts are switched off), hidden_by_settings (that kind is still off, for example follows) or overlay_unreachable (it could not be sent to the screen). |
counted_as_money | boolean | Always false |
received_at | string | When Tipjai received the event, as ISO 8601 |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"idempotency_key_required", …} | No Idempotency-Key header, or it is not in the right form |
400 | {"error":"unknown_field", …} | The body is wrong; error says which: invalid_body (not one JSON object, or over 4 KB), unknown_field, invalid_type, invalid_name, invalid_source, invalid_gift or invalid_event. The message text is English. |
409 | {"error":"in_progress"} | An event with this Idempotency-Key is still being processed. Retry with the same key after Retry-After (2 seconds). |
422 | {"error":"events_are_never_money"} | A field that looks like money was sent. Events are never money; the message names the field that was refused. |
422 | {"error":"idempotency_key_reused"} | This Idempotency-Key was already used for a different event. Use a new key for a new event. |
401 | {"error":"missing_api_key"} | No Authorization: Bearer tj_live_... header (a value that does not start with tj_live_ counts as no key) |
401 | {"error":"invalid_api_key"} | The key is not valid, or it was revoked. Create a new one in Studio. |
403 | {"error":"insufficient_scope"} | This key does not have the events:write scope. Create a key with it in Studio. |
429 | {"error":"rate_limited"} | More than 120 requests a minute on one key, too many from one IP address, or more than 60 events a minute for one creator. Wait for Retry-After, then try again; the same Idempotency-Key is fine. |
503 | {"error":"auth_unavailable"} | The key could not be checked just now. Try again after Retry-After (30 seconds). |
503 | {"error":"unavailable"} | The event could not be recorded just now. Retry with the same Idempotency-Key after Retry-After (5 seconds). |
Cache-Control no-store
curl -X POST "https://tipjai.com/api/v1/me/events" \
-H "Authorization: Bearer tj_live_..." \
-H "Idempotency-Key: yt-gift-8812" \
-H "Content-Type: application/json" \
-d '{"type":"gift","name":"Mali","source":"YouTube","gift":{"name":"Super Sticker","count":1}}'{
"id": "6c1f0d3a-8b2e-4f57-9a1c-5d7e2b4f8a39",
"object": "event",
"type": "gift",
"shown": true,
"reason": null,
"counted_as_money": false,
"received_at": "2026-10-27T13:05:12.481Z"
}There is no live request button for an endpoint that needs a key, because a key should never be typed into a web page. Use the example above in your own server-side code.
Control the subathon timer
/api/v1/me/timerScope needed timer:write
Add time to, take time from, pause or resume the subathon clock on stream, exactly like Studio's buttons. It goes through the same path as those buttons, and OBS and the public page read the new value by themselves.
- add and subtract move the clock by at most 604,800 seconds (one week) a command.
- If your clock widget is not in timer mode (timer_mode is false), the change is saved but nothing shows it yet.
- At most 30 commands a minute for one creator, counted across REST and MCP together.
Parameters
| Name | Type | Description |
|---|---|---|
body | application/json, up to 1 KB | One JSON object: action, and seconds or minutes. An unknown field is refused. |
action | enum | add, subtract, pause or resume |
seconds | 1 to 604800 | Needed for add and subtract, in whole seconds. pause and resume must not send it. |
minutes | number | Can stand in for seconds (1 minute is 60 seconds). Send one or the other, never both. |
Response
| Field | Type | Description |
|---|---|---|
action | string | The action you sent |
running | boolean | true when the clock is running, false when it is paused |
shows_seconds | number | What the stream shows right after the command, in whole seconds (the base clock plus the time this round's tips added) |
timer_ends_at | string | null | When the base clock ends, null while it is paused |
paused_seconds | number | The seconds the base clock holds while it is paused |
timer_mode | boolean | false when your clock widget is not in timer mode: the change is saved, but nothing shows it yet |
When it fails
| Status | Body | Meaning |
|---|---|---|
400 | {"error":"invalid_timer_command", …} | The command is wrong: for example action is not add, subtract, pause or resume, add or subtract has no seconds, pause or resume sends seconds, both seconds and minutes are sent, or a field is unknown. The message says which, in English. |
404 | {"error":"creator_not_found"} | No creator page belongs to this key |
401 | {"error":"missing_api_key"} | No Authorization: Bearer tj_live_... header (a value that does not start with tj_live_ counts as no key) |
401 | {"error":"invalid_api_key"} | The key is not valid, or it was revoked. Create a new one in Studio. |
403 | {"error":"insufficient_scope"} | This key does not have the timer:write scope. Create a key with it in Studio. |
429 | {"error":"rate_limited"} | More than 120 requests a minute on one key, too many from one IP address, or more than 30 timer commands a minute for one creator (REST and MCP together). Wait for Retry-After, then try again. |
503 | {"error":"auth_unavailable"} | The key could not be checked just now. Try again after Retry-After (30 seconds). |
503 | {"error":"timer_unavailable"} | The clock did not change. Try again after Retry-After (5 seconds). |
Cache-Control no-store
curl -X POST "https://tipjai.com/api/v1/me/timer" \
-H "Authorization: Bearer tj_live_..." \
-H "Content-Type: application/json" \
-d '{"action":"add","seconds":300}'{
"action": "add",
"running": true,
"shows_seconds": 5400,
"timer_ends_at": "2026-10-27T15:30:00.123456+00:00",
"paused_seconds": 0,
"timer_mode": true
}There is no live request button for an endpoint that needs a key, because a key should never be typed into a web page. Use the example above in your own server-side code.