Invoking APIs
SurrealDB allows you to define custom API endpoints that expose database operations through HTTP-style routes. The JavaScript SDK provides the .api() method to invoke these endpoints with full type safety, custom headers, and structured responses.
API References
Accessing API endpoints
To invoke user-defined endpoints, call .api() on any Surreal, SurrealSession, or SurrealTransaction instance. The returned SurrealApi object exposes HTTP-style methods like .get(), .post(), .put(), .delete(), and .patch().
const api = db.api();
const users = await api.get('/users').value();
const newUser = await api.post('/users', {
name: 'John Doe',
email: 'john@example.com',
}).value();
By default, API calls return a response object containing body, status, and headers. Chaining .value() returns only the response body directly.
const response = await api.get('/users');
console.log(response.status);
console.log(response.headers);
console.log(response.body);
const users = await api.get('/users').value();
console.log(users);
Defining type-safe APIs
You can define TypeScript types for your API paths to get compile-time type checking on both request bodies and responses. Each path maps HTTP methods to a tuple of [RequestBody, ResponseBody].
type MyApi = {
'/users': {
get: [void, User[]];
post: [CreateUserInput, User];
};
[K: `/users/${string}`]: {
get: [void, User];
put: [UpdateUserInput, User];
delete: [void, void];
};
};
const api = db.api<MyApi>();
const users: User[] = await api.get('/users').value();
You can set headers on individual requests by chaining .header(), or set default headers on the API instance using api.header(). Setting a header value to null removes it.
const result = await api.get('/protected')
.header('X-Custom-Header', 'value')
.value();
api.header('Content-Type', 'application/json');
api.header('Content-Type', null);
Using a path prefix
When working with a group of related endpoints, you can pass a prefix to .api(). All subsequent calls will be relative to that prefix.
const usersApi = db.api<UserPaths>('/users');
const allUsers = await usersApi.get('/').value();
const user = await usersApi.get('/123').value();
Handling API errors
When an API call fails, the SDK throws an UnsuccessfulApiError. This error includes the path, HTTP method, and the full response object.
import { UnsuccessfulApiError } from 'surrealdb';
try {
await api.get('/users/999').value();
} catch (error) {
if (error instanceof UnsuccessfulApiError) {
console.error(`${error.method} ${error.path} failed`);
console.error('Status:', error.response.status);
}
}
Learn more
