Complete API Documentation

API Documentation

Complete guide to using VeyraAPI. Learn about authentication, endpoints, caching, rate limiting, and best practices.

Try API Tester View Endpoints

Getting Started

VeyraAPI provides a simple, fast, and reliable way to search, fetch metadata, and stream music from YouTube. All endpoints are RESTful and return JSON responses. Authentication is required for all API calls.

Base URL

https://veyra-api.zeabur.app/api/api

Authentication

All API requests require an API key. You can provide it in two ways:

  • ✓
    ?api_key=YOUR_API_KEY as a query parameter
  • ✓
    X-API-Key: YOUR_API_KEY as a header
Note: Contact the API administrator to obtain an API key. Each key has configurable rate limits and usage tracking.

Core Endpoints

GET

/api/search

Search for music tracks on YouTube. Results are cached for 1 hour for optimal performance.

Parameter Type Required Description
query string Yes Search keywords or artist name
limit integer No Max results (1-50, default: 10)
api_key string Yes Your API key

Example Request:

GET /api/search?query=lofi&limit=5&api_key=YOUR_KEY

Example Response:

{
  "success": true,
  "query": "lofi",
  "count": 5,
  "cached": false,
  "results": [
    {
      "id": "jfKfPfyJRdk",
      "title": "lofi hip hop radio",
      "artist": "Lofi Girl",
      "duration": "LIVE",
      "thumbnail": "https://i.ytimg.com/...",
      "url": "https://youtube.com/watch?v=jfKfPfyJRdk"
    }
  ]
}
GET

/api/track

Get detailed metadata and download URL for a specific YouTube track.

Parameter Type Required Description
url string Yes YouTube video URL or ID
video boolean No Set to 'true' for video (default: audio only)
api_key string Yes Your API key

Example Request:

GET /api/track?url=https://youtube.com/watch?v=dQw4w9WgXcQ&api_key=YOUR_KEY

Example Response:

{
  "success": true,
  "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
  "cdnurl": "{apiUrl}/api/stream/dQw4w9WgXcQ?api_key=YOUR_KEY",
  "name": "Rick Astley - Never Gonna Give You Up",
  "tc": "dQw4w9WgXcQ",
  "cover": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "duration": 213,
  "platform": "youtube"
}
GET

/api/stream/:videoId

Stream or download audio/video files. Files are cached for 7 days with progressive streaming support.

Parameter Type Required Description
videoId string Yes YouTube video ID (in URL path)
video boolean No Set to 'true' for video format
api_key string Yes Your API key

Example Request:

GET /api/stream/dQw4w9WgXcQ?api_key=YOUR_KEY
Streaming Features:
- Progressive streaming on cache miss for faster time-to-first-byte
- HTTP Range requests supported for seeking
- Automatic quality selection (best audio/video)
- 7-day cache retention

Performance & Caching

VeyraAPI implements multiple caching layers for optimal performance:

Caching Strategy

  • ✓
    Search Cache: 1 hour TTL, in-memory LRU cache
  • ✓
    Video Info Cache: 1 hour TTL, max 100 entries
  • ✓
    File Cache: 7 days retention, automatic cleanup
  • ✓
    API Key Cache: 5 minutes TTL to reduce database queries

Response Headers

All API responses include performance headers:

  • •
    X-Response-Time Request processing time in milliseconds
  • •
    Server-Timing Detailed timing information
  • •
    X-Cache HIT or MISS status for search results
  • •
    Cache-Control Caching directives for media files

Benchmarks

Endpoint Cached Uncached
Search < 100ms < 2s
Track Info < 50ms < 1s
Stream < 500ms 5-10s (first download)

Rate Limiting

API keys have configurable rate limits to ensure fair usage and system stability.

Default Limits

  • •
    Per Minute: 60 requests
  • •
    Per Hour: 1,000 requests
  • •
    Per Day: 10,000 requests
Rate Limit Exceeded: When you exceed your rate limit, the API returns a 429 status code with a retryAfter value in seconds.

Rate Limit Response:

{
  "error": "Rate limit exceeded",
  "message": "Max 60/min",
  "retryAfter": 42
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code Meaning Description
200 OK Request successful
400 Bad Request Invalid parameters
401 Unauthorized Missing or invalid API key
403 Forbidden API key disabled
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Best Practices

  • ✓
    Respect Rate Limits: Implement exponential backoff when receiving 429 responses
  • ✓
    Cache Responses: Cache search and metadata results on your end to reduce API calls
  • ✓
    Use HTTPS: Always use HTTPS for secure communication
  • ✓
    Handle Errors Gracefully: Implement proper error handling for all status codes
  • ✓
    Monitor Usage: Track your API usage to optimize requests
  • ✓
    Use Versioned Endpoints: Use /api/v1/* endpoints for better stability

Support & Contact

For questions, issues, or feature requests:

  • •
    Contact the API administrator via Telegram bot
  • •
    Check the API reference for detailed endpoint documentation
  • •
    Test endpoints using the interactive tester