Skip to main content

​
Overview

RoZod provides a simple, type-safe interface for making requests to Roblox APIs. The fetchApi function handles authentication, CSRF tokens, and error parsing automatically.

​
Basic request structure

Every API request in RoZod follows this pattern:
1

Import the fetchApi function and endpoint

import { fetchApi } from 'rozod';
import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';
2

Call fetchApi with the endpoint and parameters

const response = await fetchApi(getUsersUserdetails, { 
  userIds: [1, 123456] 
});
3

Handle the response

if (isAnyErrorResponse(response)) {
  console.error(response.message);
} else {
  console.log(response.data[0].displayName);
}

​
Complete example

Here’s a complete example fetching game icons: 
import { fetchApi } from 'rozod';
import { getGamesIcons } from 'rozod/lib/endpoints/gamesv1';

const response = await fetchApi(getGamesIcons, { 
  universeIds: [1534453623, 65241] 
});

console.log(response.data);
All parameters are fully type-checked. TypeScript will show you exactly what parameters each endpoint accepts.

​
Error handling

RoZod provides two approaches to error handling:

​
Union type approach (default)

By default, fetchApi returns either the success type or an AnyError object: 
import { fetchApi, isAnyErrorResponse } from 'rozod';
import { getGamesIcons } from 'rozod/lib/endpoints/gamesv1';

const res = await fetchApi(getGamesIcons, { universeIds: [1534453623] });

if (isAnyErrorResponse(res)) {
  console.error(res.message);
} else {
  console.log(res.data); // Fully typed success response
}
Use isAnyErrorResponse() to narrow the type and get full TypeScript safety for both success and error cases.

​
Throw on error

If you prefer try/catch blocks, enable throwOnError: 
try {
  const res = await fetchApi(
    getGamesIcons, 
    { universeIds: [1534453623] }, 
    { throwOnError: true }
  );
  console.log(res.data);
} catch (err) {
  console.error((err as Error).message);
}

​
Request options

You can customize requests with additional options: 
const response = await fetchApi(
  getUsersUserdetails,
  { userIds: [123456] },
  {
    headers: {
      'Cookie': '.ROBLOSECURITY=your_cookie_here'
    }
  }
);

​
Getting raw responses

If you need access to the raw Response object, use returnRaw: 
const resp = await fetchApi(
  getGamesIcons, 
  { universeIds: [1534453623] }, 
  { returnRaw: true }
);

// Access raw response properties
console.log(resp.status);
console.log(resp.headers.get('content-type'));

const json = await resp.json();
When using returnRaw: true, you must manually parse the response body and handle errors.

​
Type safety

RoZod endpoints are fully typed, providing autocomplete and type checking: 
import { fetchApi } from 'rozod';
import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';

const response = await fetchApi(getUsersUserdetails, { 
  userIds: [1, 123456] 
});

if (!isAnyErrorResponse(response)) {
  // TypeScript knows the exact shape of response.data
  response.data.forEach(user => {
    console.log(user.displayName); // ✓ Type-safe
    console.log(user.username);    // ✓ Type-safe
    console.log(user.invalid);     // ✗ TypeScript error
  });
}

​
Next steps

Pagination

Learn how to handle paginated API responses

Batch processing

Process large requests efficiently

Custom endpoints

Define your own API endpoints

OpenCloud

Use Roblox OpenCloud APIs

Build docs developers (and LLMs) love

Get started for freeTalk to us