Quickstart

Prepare a ShortsMonkey account and a server-side terminal with HTTPS access. The cURL example needs cURL; JavaScript needs Node.js with fetch; Python needs requests. All keys shown are placeholders: use a key from your own account.

Sign in, open API Console, and copy the full key from the one-time reveal. REST requests require api:read; MCP tools require mcp:read. Select both for both integrations, or only the permission your integration needs.

export SHORTSMONKEY_API_KEY="sm_live_..."

GET /v1/auth/verify, GET /v1/credits, GET /v1/credits/costs, health checks, and key management do not consume the 10 daily data calls. Keys still require authentication and ownership checks.

Run curl -i https://api.shortsmonkey.com/v1/auth/verify -H "Authorization: Bearer $SHORTSMONKEY_API_KEY" in your terminal. This REST check also requires api:read. Expect HTTP 200, then confirm data.authenticated is true and data.scopes contains api:read. Successful authentication does not guarantee a non-empty ranking.

Run one of the examples below; you do not need to execute all three. The request reads a stored stable Chinese long-video snapshot and does not trigger a live YouTube fetch. Check the HTTP status first. For a non-200 response, read error.code instead of treating the error JSON as ranking data.

data.all_data.items contains the current page before request filters; data.filter_data.items contains the current page after defaults and request filters. Either array may be empty and their counts may differ; an empty array is not an authentication failure. Use meta.snapshot_at to assess the age of the data and retain meta.request_id for diagnostics.

For another page, pass all_data.next_cursor as all_cursor and filter_data.next_cursor as filter_cursor, keeping the original filters. null ends that result set; do not swap the cursors. Each successful new REST data request uses a daily call. credits.unlimited being true does not mean unlimited data requests; check daily_usage.remaining.

401 INVALID_API_KEY: check the full sm_live_ key, the space after Bearer, the environment variable, and whether the key expired, was revoked, or passed its rotation grace period. For 403 INSUFFICIENT_SCOPE, check api:read; for 403 ACCOUNT_DISABLED, check account status and contact support. Repeated retries do not repair authentication or permissions.

Distinguish 429 by error.code: API_DAILY_LIMIT_REACHED requires waiting until 00:00 Asia/Shanghai; RATE_LIMITED requires reducing frequency and simultaneous requests and honoring Retry-After when supplied. 503 DATA_STALE means the stored snapshot is too old; SERVICE_UNAVAILABLE means temporary unavailability. Use bounded retries with backoff and retain the request ID.

Keep the key in a server-side environment variable or secret store and send it in the Authorization header. Do not put it in browser code, URLs, Git, screenshots, logs, or analytics. Share only the request ID, operation, time, status, and error code for diagnostics. If exposed, rotate or revoke the key in the console and update your server configuration.