Four steps to get going

1. Add the API address to your app

   Put this line in your .env.local file. Every request your app makes starts with this address.

   NEXT_PUBLIC_API_BASE_URL=https://nysc-api-staging.80.241.222.89.sslip.io/api/v1

   Copy

   On Vite, the same value goes in a variable starting with VITE_, for example VITE_API_BASE_URL.

2. Check that you can reach it

   Open the health check in a browser, or run the command. You should see {"status":"ok"}.

   curl https://nysc-api-staging.80.241.222.89.sslip.io/api/v1/health

   Copy

   Open the health check

3. Run your app on an allowed address

   The browser only lets your app call the API from these two addresses. Anything else is blocked by CORS (see the glossary).

   http://localhost:3000http://localhost:5173

   Deploying a preview (for example on Vercel or Netlify)? Send the backend team the exact address so it can be added. Until then, calls from that address will fail in the browser even though the API is up.

4. Use the contract, not Swagger

   Swagger at /docs is turned off on purpose, because staging runs in production mode. The reviewed contract lives in the repo:

   Every endpoint and field

   docs/api/openapi.v1.json

   How to use it

   docs/api/README.md

   User stories S1 to S11

   docs/api/user-stories.md

   Tip: drop openapi.v1.json into editor.swagger.io, Postman or Insomnia to browse it, or generate a typed client from it.

Before you start testing

// lib/api.ts
const BASE = process.env.NEXT_PUBLIC_API_BASE_URL!;

export async function api<T>(path: string, init: RequestInit = {}, token?: string): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      "Content-Type": "application/json",
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
      ...init.headers,
    },
  });
  if (res.status === 501) throw new Error(`${path} is not built yet (501)`);
  if (!res.ok) throw await res.json().catch(() => new Error(res.statusText));
  return res.status === 204 ? (undefined as T) : res.json();
}

// usage
const health = await api<{ status: string }>("/health");

The helper assumes the access token is sent as Authorization: Bearer …. Confirm how tokens are sent and the exact error shape in docs/api/README.md.

Where to go next