The ZakGT API is a REST API that allows developers to programmatically interact with the ZakGT platform. Whether you are building a third-party integration, automating workflows, or extending ZakGT into your own applications, this guide covers everything you need to get started and operate reliably.
The API is versioned under /api/v1/ and follows standard REST conventions: JSON request/response bodies, standard HTTP status codes, and bearer token authentication. All API communication is over HTTPS.
Base URL and API Versioning
Base URL (production):
https://api.zakgt.net/api/v1/
The API uses version prefixes in the URL path. The current stable version is v1. When breaking changes are introduced, a new version prefix is added — v1 endpoints remain available for a defined deprecation period.
Protocol
HTTPS only — HTTP redirects to HTTPS
Format
JSON request and response bodies
Auth
Bearer token (access token from login)
Authentication Flow
ZakGT uses token-based authentication. To make authenticated API calls, you need an access token. Here is the complete authentication flow:
Step 1 — Login to Get Tokens
On success, the response includes an access_token and a refresh_token. The access token is short-lived. The refresh token is used to get a new access token without requiring the user to log in again.
Step 2 — Include the Token in Requests
Authorization header:
Authorization: Bearer <access_token>
Add this header to every authenticated API call. Requests without this header to protected endpoints return 401 Unauthorized.
Step 3 — Refresh When the Token Expires
POST /api/v1/auth/refresh
{
"refresh_token": "your-refresh-token"
}
When you receive a 401 response on a request that was previously working, call the refresh endpoint to get a new access token. Store both tokens securely — never expose them in client-side code or public repositories.
Core API Endpoint Categories
The ZakGT API covers every major platform feature. Endpoints are organized into these categories:
Authentication
/api/v1/auth/
POST /loginLog in with email and password. Returns access and refresh tokens.
POST /registerRegister a new user account.
POST /refreshExchange a refresh token for a new access token.
POST /logoutInvalidate the current session token.
POST /forgot-passwordRequest a password reset email.
POST /reset-passwordSet a new password using a reset token.
User & Profile
/api/v1/users/
GET /meGet the current authenticated user's profile data.
PUT /meUpdate profile fields (display name, bio, links).
GET /{user_id}Get a public user profile by ID.
GET /me/statsGet platform activity stats for the current user.
DELETE /meDeactivate the current user's account.
Wallet & Coins
/api/v1/wallet/
GET /balanceGet the current coin balance for the authenticated user.
GET /transactionsList all coin transaction history with pagination.
POST /topup/stripeInitiate a Stripe top-up session.
POST /topup/paypalInitiate a PayPal top-up session.
POST /topup/abaInitiate an ABA Pay top-up request.
Marketplace
/api/v1/mart/
GET /productsList marketplace products with filtering and sorting.
GET /products/{id}Get a single product by ID.
POST /productsCreate a new marketplace listing (requires shop).
PUT /products/{id}Update a listing you own.
DELETE /products/{id}Delete a listing you own.
POST /products/{id}/purchasePurchase a product using ZakGT Coins.
Live Streaming
/api/v1/live/
GET /sessionsList currently active live streams.
GET /sessions/{id}Get details for a specific live stream session.
POST /sessions/startStart a new live stream session.
POST /sessions/{id}/endEnd your live stream session.
Tools
/api/v1/tools/
GET /List all available tools with categories and access requirements.
GET /{tool_id}Get detailed info about a specific tool.
POST /{tool_id}/purchasePurchase access to a specific tool.
GET /my-toolsList all tools the current user has access to.
ZakGT AI
/api/v1/ai/
POST /chatSend a message to ZakGT AI and receive a reply. Spends AIM based on the tier persona used.
POST /studioGenerate an image (Z7 Studio tier). Spends AIM per image.
GET /usage/historyGet your AIM usage history — the per-call trust ledger.
Developer Access Keys
/api/v1/developer/
POST /api-keysCreate a personal access key (zak_live_…). The secret is shown once only.
GET /api-keysList your keys (prefix + status — never the full secret).
DELETE /api-keys/{id}Revoke a key immediately — it stops working at once.
GET /api-keys/{id}/usageSee the per-call usage logged for one key.
Response Format and Status Codes
All ZakGT API responses use standard HTTP status codes. Successful responses return JSON with a consistent structure. Error responses include a message field describing what went wrong.
Success Response Example
HTTP 200 OK
{
"status": "ok",
"data": { ... },
"request_id": "..."
}
Error Response Example
HTTP 422 Unprocessable Entity
{
"detail": "email: value is not a valid email address"
}
| Status Code | Meaning | Common Cause |
|---|---|---|
| 200 OK | Request succeeded | Standard successful response |
| 201 Created | Resource created | POST that creates a new entity |
| 400 Bad Request | Invalid request format | Missing or malformed required fields |
| 401 Unauthorized | Authentication failed | Missing, expired, or invalid token |
| 403 Forbidden | Permission denied | Valid token but insufficient role/tier |
| 404 Not Found | Resource not found | Invalid ID or deleted resource |
| 422 Validation Error | Input validation failed | Field value does not meet schema requirements |
| 429 Too Many Requests | Rate limit exceeded | Too many requests in a time window |
| 500 Internal Error | Server error | Unexpected server-side failure |
Rate Limits
Rate limits are enforced per authenticated user — and, for programmatic calls, per access key, so one key can never exhaust another's allowance. AI chat is the main rate-limited surface; other endpoints follow standard abuse-protection limits.
| Endpoint | Limit | Scope |
|---|---|---|
| POST /ai/chat | 30 req / min | Per user — and per access key for zak_live_ calls |
| Other endpoints | Standard limits | Abuse-protection limits per user / IP |
When you exceed a rate limit, the API returns 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait before retrying.
Best practice: implement exponential backoff
When handling 429 responses, wait for the Retry-After period and then retry with increasing delays if the issue persists. Avoid immediately retrying in a tight loop — this wastes your rate limit allowance and will not resolve the underlying throttling.
Integration Best Practices
These patterns will make your ZakGT integration more reliable, maintainable, and secure:
Never expose tokens in client-side code
Access tokens and refresh tokens must never appear in browser JavaScript, mobile app code bundles, or public Git repositories. Use environment variables on your server side, and never log token values.
Implement transparent token refresh
Build your HTTP client layer to automatically detect 401 responses, attempt a token refresh, and retry the original request once. This prevents your users from experiencing session interruptions when access tokens expire.
Cache data where appropriate
Static-ish data like tool listings and product catalogues changes infrequently. Cache these responses with a short TTL (5-15 minutes) rather than fetching on every page load. This reduces API usage and improves performance.
Use pagination correctly
List endpoints (products, transactions, users) are paginated. Always use the cursor or page parameters returned in the response to fetch subsequent pages, rather than incrementing an offset guess. This is especially important for large datasets.
Handle all status codes explicitly
Do not only handle 200 and ignore the rest. Build explicit handlers for 401 (refresh tokens), 403 (permissions error, surface to user), 404 (resource gone), 422 (validation error, show to user), and 429 (rate limit, back off).
Use a dedicated test account
When developing, use a separate ZakGT account specifically for testing. This avoids polluting your personal account's activity history and coin balance with test transactions.
Log request IDs for support
API responses include a request ID in the response headers. Log these IDs in your application. When reporting an issue to ZakGT support, including the request ID dramatically speeds up investigation on the server side.
Check the Content-Type header
All request bodies must include Content-Type: application/json. Requests without this header may be rejected or parsed incorrectly by the server.
Common Integration Patterns
Here are the most common ways developers integrate with the ZakGT API:
User authentication passthrough
Build a login/register flow in your own app that calls ZakGT auth endpoints. Store the tokens in your app state and use them for all subsequent API calls on behalf of the user. This is the pattern used by the ZakGT mobile app and desktop client.
Marketplace integration
Read and display ZakGT marketplace listings in an external app or website. Use the public product endpoints with your own API key to fetch product data without user authentication.
Wallet and payment automation
Automate coin top-up flows or build custom purchase experiences using the wallet endpoints. All payment provider flows are handled server-side — your integration just needs to initiate the session and handle the callback.
Tool catalogue sync
Pull the ZakGT tool catalogue to display available tools in a custom directory, internal dashboard, or integration layer. Tools include metadata like category, access tier, and pricing.
Getting API Access
There are two access paths depending on your use case:
User-Level Access
Any registered ZakGT user can authenticate with their account and make calls on their own behalf. Usage is billed to your own Wallet and AIM balance, and rate limits follow your account tier.
How to start:
Create your account at zakgt.net, then create a personal access key (see below) to use ZakGT AI from your own apps and tools.
Enterprise API Access
Enterprise accounts receive the highest rate limits and priority API infrastructure. For high-volume integrations, a ZakGT Enterprise account is the recommended foundation.
How to start:
Upgrade to Enterprise via the Subscribe section in your dashboard, then contact support to discuss custom integration needs.
Personal Access Keys
The simplest way to call ZakGT AI from your own apps, scripts, or tools is with a personal access key. A key is tied to your own account, so every call spends only your own AIM at the same tier prices you already pay on the website, desktop, Telegram, and mobile — there is no separate pricing for keys.
Two steps to get started
Create a key in your account
Open your account, go to the Access Keys area, and create a new key. The key is shown to you only once at creation — copy it and store it somewhere safe, because it cannot be displayed again later.
Use the key in your app
Add the key to your own application and use it to send ZakGT AI requests. Each request runs against your account and spends your own AIM at the normal tier rate — Z0 is free for your daily allowance, and higher tiers cost their usual AIM amount per call.
Keys stay in your control
- •You can create more than one key — for example, a separate key per app or per device.
- •You can revoke any key at any time. Once revoked, it stops working immediately and no further AIM can be spent through it.
- •A key only ever spends your own AIM — it never charges another user and never auto-converts your coins. You exchange coins to AIM yourself in your Wallet.
- •Treat a key like a password: keep it out of public code and shared screenshots. If a key is ever exposed, revoke it and create a new one.
Summary
The ZakGT API follows standard REST conventions with JSON bodies, bearer token authentication, and versioned endpoints under /api/v1/. Authentication is handled through a login-refresh token pair. Core categories include auth, user profiles, wallet and coins, marketplace, live streaming, tools, ZakGT AI, and developer access keys. Rate limits are enforced per user — and per access key for programmatic calls — with AI chat limited to 30 requests per minute.
The most important integration practices are: never exposing tokens in client-side code, implementing transparent token refresh, handling all HTTP status codes explicitly, and using pagination correctly. These four practices account for the majority of integration reliability issues developers encounter.