API Reference
API Reference
Complete reference for all Soke API endpoints, including request/response formats and error codes.
API Overview
Base URL
https://api.usesoke.ai/api/v1Content Type
All requests must include Content-Type: application/json. All responses are JSON.
Response Format
Every successful response follows this envelope:
{
"success": true,
"data": {
// Endpoint-specific response data
},
"meta": {
"platform": "youtube",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"processing_time_ms": 142
}
}Error Format
Error responses use the same envelope with an error object:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description of the error.",
"details": {}
},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}Error Codes
| Code | HTTP Status | Description |
|---|---|---|
BAD_REQUEST | 400 | Invalid request parameters or validation failure |
UNAUTHORIZED | 401 | Missing or invalid authentication |
FORBIDDEN | 403 | Insufficient permissions |
SUBSCRIPTION_REQUIRED | 403 | No active subscription |
NOT_FOUND | 404 | Resource not found |
INSUFFICIENT_CREDITS | 402 | Not enough credits for the operation |
RATE_LIMIT_EXCEEDED | 429 | Rate limit or monthly quota exceeded |
PLATFORM_NOT_IMPLEMENTED | 501 | Requested platform is not yet supported |
INTERNAL_ERROR | 500 | Internal server error |
Platform Parameter
Most endpoints accept an optional platform parameter. Currently only "youtube" is supported. Other values return 501 Not Implemented.
TikTok, Instagram, LinkedIn, X/Twitter, and Podcast support are on the roadmap.
Quota-Tracked Endpoints
The following endpoints consume credits and count toward your rate limit:
| Category | Endpoint | Method |
|---|---|---|
| Research | /research/keywords | POST |
| Research | /research/content | POST |
| Content | /content/optimize-title | POST |
| Content | /content/score | POST |
| Content | /content/generate-description | POST |
| Chat | /chat/completions | POST |
| Thumbnail | /thumbnail/generate | POST |
| Thumbnail | /thumbnail/generate-background | POST |
| Transcription | /transcription | POST |