REST API Conventions

This guide specifies API standards, base endpoints, authentication requirements, and HTTP error formats for integrating with the StackVid REST API.

---

1. Base URL & Protocol

All requests must be transmitted securely over HTTPS:

https://api.stackvid.dev/api

• Payloads and responses use standard JSON (application/json) encoded in UTF-8.
• Timestamps are represented in international ISO-8601 UTC format (e.g. 2026-10-01T12:00:00.000Z).

---

2. Authentication Header

All programmatic API endpoints require authentication via an API Key passed in the HTTP request header:

X-API-Key: tk_live_YOUR_API_KEY

Generating API Keys

You can generate, copy, and revoke API keys anytime in your Dashboard → API Keys. Keys start with tk_live_... and are activated instantly.

---

3. HTTP Status Codes

StackVid returns standard, predictable HTTP status codes:

Code	Status	Meaning & Troubleshooting
200	OK	Operation executed successfully with response payload.
201	Created	Resource created successfully (e.g. Presigned Upload URL generated).
400	Bad Request	Invalid input parameters (e.g. invalid videoUrl, HTML page returned, or missing fields).
401	Unauthorized	Missing X-API-Key header or the provided key is invalid / revoked.
402	Payment Required	Insufficient credit balance in your wallet to cover the operation.
429	Too Many Requests	Rate limit exceeded (Default: 60 requests/minute).
500	Internal Server Error	Upstream network disruption or social platform error (100% credits automatically refunded).

---

4. Error Response Structure

When an error occurs (status code >= 400), the API returns a consistent JSON payload:

Insufficient Balance (402 Payment Required):

{
  "statusCode": 402,
  "message": "Insufficient credit balance. Required: 5, Available: 2",
  "error": "Payment Required"
}

Validation Error (400 Bad Request):

{
  "statusCode": 400,
  "message": [
    "videoUrl must be a valid HTTP or HTTPS URL"
  ],
  "error": "Bad Request"
}

Zero-Risk Automatic Refund

If an API operation fails due to unreachable video URLs or upstream platform network drops, the Two-Phase Commit pipeline automatically rolls back and refunds 100% of deducted credits back to your wallet immediately.