cURL Examples¶

Command-line examples using cURL for the SubX API.

Setup¶

# Set your API key as environment variable
export SUBX_API_KEY="{YOUR_API_KEY_HERE}"

Basic Examples¶

Health Check¶

curl https://subx-api.duckdns.org/api/health

Search by Title¶

curl -X GET "https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=10" \
  -H "Authorization: Bearer $SUBX_API_KEY"

Search by IMDb ID¶

curl -X GET "https://subx-api.duckdns.org/api/subtitles/search?imdb_id=tt0773262&limit=20" \
  -H "Authorization: Bearer $SUBX_API_KEY"

Get Subtitle Details¶

curl -X GET "https://subx-api.duckdns.org/api/subtitles/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $SUBX_API_KEY"

Download Subtitle¶

curl -X GET "https://subx-api.duckdns.org/api/subtitles/550e8400-e29b-41d4-a716-446655440000/download" \
  -H "Authorization: Bearer $SUBX_API_KEY" \
  -o subtitle.srt

Advanced Examples¶

Pretty-print JSON with jq¶

curl -X GET "https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=5" \
  -H "Authorization: Bearer $SUBX_API_KEY" | jq '.'

Extract just titles¶

curl -s -X GET "https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=10" \
  -H "Authorization: Bearer $SUBX_API_KEY" | jq -r '.items[].title'

Search and download first result¶

#!/bin/bash
RESULT=$(curl -s -X GET "https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=1" \
  -H "Authorization: Bearer $SUBX_API_KEY")

SUBTITLE_ID=$(echo $RESULT | jq -r '.items[0].id')

if [ "$SUBTITLE_ID" != "null" ]; then
  curl -X GET "https://subx-api.duckdns.org/api/subtitles/$SUBTITLE_ID/download" \
    -H "Authorization: Bearer $SUBX_API_KEY" \
    -o "dexter.srt"
  echo "Downloaded: dexter.srt"
else
  echo "No subtitles found"
fi

See the Quickstart Guide for more examples.