TypeScript Client Guide

Use fetch with TypeScript interfaces for type-safe API calls. Define response types to get autocomplete and compile-time checks.

Prerequisites

TypeScript 5.0+
Node.js 18+ or modern browser

Authentication

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

interface ApiOptions {
  apiKey?: string;
}

async function shortedApi<T>(
  path: string,
  body: Record<string, unknown>,
  options?: ApiOptions
): Promise<T> {
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };

  if (options?.apiKey) {
    headers["Authorization"] = `Bearer ${options.apiKey}`;
  }

  const response = await fetch(`https://shorts-uiekqxovma-km.a.run.app${path}`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json() as Promise<T>;
}

Example: Get Top Shorted Stocks

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

interface ShortPosition {
  productCode: string;
  productName: string;
  currentPercent: number;
  previousPercent: number;
  industry: string;
  companyName: string;
}

interface GetTopShortsResponse {
  stocks: ShortPosition[];
  totalCount: number;
}

const response = await fetch(
  "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ limit: 10, offset: 0 }),
  }
);

const data: GetTopShortsResponse = await response.json();
data.stocks.forEach((stock) => {
  console.log(`${stock.productCode}: ${stock.currentPercent}%`);
});

Example: Get Stock Details

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

interface Stock {
  productCode: string;
  companyName: string;
  currentPercent: number;
  industry: string;
  description: string;
}

interface GetStockResponse {
  stock: Stock;
}

const response = await fetch(
  "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetStock",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ productCode: "BHP" }),
  }
);

const { stock }: GetStockResponse = await response.json();
console.log(`${stock.companyName}: ${stock.currentPercent}%`);

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.

interface ApiError {
  code: string;
  message: string;
}

async function safeApiCall<T>(
  path: string,
  body: Record<string, unknown>
): Promise<T> {
  const response = await fetch(`https://shorts-uiekqxovma-km.a.run.app${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY",
    },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") ?? "60";
    throw new Error(`Rate limited. Retry after ${retryAfter}s`);
  }

  if (!response.ok) {
    const error: ApiError = await response.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return response.json() as Promise<T>;
}

All Endpoints

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