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

Method	Description
`db.api(prefix?)`	Creates a SurrealApi instance for invoking user-defined endpoints
`api.get(path)`	Invokes a GET endpoint
`api.post(path, body?)`	Invokes a POST endpoint
`api.invoke(path, request?)`	Invokes an endpoint with a custom request object

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().

// Obtain the API reference
const api = db.api();

// Execute a GET request
const users = await api.get('/users').value();

// Execute a POST request
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);	// 200
console.log(response.headers);	// { 'content-type': 'application/json' }
console.log(response.body);	// [ { id: RecordId, name: 'John Doe', email: 'john@example.com' } ]

const users = await api.get('/users').value();

console.log(users); // [ { id: RecordId, name: 'John Doe', email: 'john@example.com' } ]

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].

// Define API types using an object literal
type MyApi = {
    '/users': {
        get: [void, User[]];
        post: [CreateUserInput, User];
    };
    [K: `/users/${string}`]: {
        get: [void, User];
        put: [UpdateUserInput, User];
        delete: [void, void];
    };
};

// Pass the custom API types to the .api() method
const api = db.api<MyApi>();

// All handlers will now be type-safe
const users: User[] = await api.get('/users').value();

Setting request headers

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.

// Single-request header
const result = await api.get('/protected')
    .header('X-Custom-Header', 'value')
    .value();

// Global header
api.header('Content-Type', 'application/json');

// Remove global header
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

SurrealApi API reference for the complete list of methods and type parameters
ApiPromise API reference for response configuration options
DEFINE API for defining custom API endpoints in SurrealQL