cURL Client Guide

cURL is a command-line tool for making HTTP requests. It comes pre-installed on macOS and most Linux distributions.

Prerequisites

cURL installed (pre-installed on macOS/Linux)
A terminal or shell

Authentication

Include your API key in the Authorization header as a Bearer token. Public endpoints work without authentication but have lower rate limits.

# Authenticated request with Bearer token
curl -X POST "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"limit": 10}'

Example: Get Top Shorted Stocks

Retrieve the most heavily shorted stocks on the ASX, sorted by short interest percentage.

curl -X POST "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "offset": 0
  }'

Example: Get Stock Details

Fetch detailed information about a specific stock by its ASX code.

curl -X POST "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetStock" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "BHP"
  }'

Error Handling

The API returns standard HTTP status codes. Rate limited requests return 429 with a Retry-After header. Always check the response status before parsing the body.

# Check HTTP status code
response=$(curl -s -w "\n%{http_code}" -X POST \
  "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -eq 429 ]; then
  echo "Rate limited. Check Retry-After header."
elif [ "$http_code" -ne 200 ]; then
  echo "Error $http_code: $body"
else
  echo "$body" | jq .
fi

All Endpoints

See the full API reference for all available endpoints, request/response schemas, and the interactive "Try It" panel.