HTTP API

HTTP API

Overview

The HTTP API is a RESTful API that allows you to interact with a Triplit Cloud production server or the Triplit Node server (opens in a new tab) that you can host yourself. It's useful if your client can't connect over WebSockets, or if your application wants to forgo the local cache and optimistic updates that the Triplit sync protocol provides. This can be useful for applications that need certainty about the state of the database, or for migrating data to Triplit from other services.

Authentication

The HTTP API, like the Triplit sync protocol, uses JSON Web Tokens (opens in a new tab) (JWT) for authentication. If you're communicating with a Triplit Cloud production server, you'll need to use your project's Service or Anonymous Token from the Triplit Cloud dashboard (opens in a new tab) for your project. If you're communicating with a Node server that you control, you'll need a properly formed JWT with the correct claims. Using the Triplit CLI and triplit dev command will automatically generate acceptable Service and Anonymous tokens for you.

With your token in hand, set up your HTTP client to send the token in the Authorization header with the Bearer scheme. Using the Fetch API, it would look like this:

// Request
await fetch('https://<project-id>.triplit.io/<route>', {
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
});

TriplitClient.http and HttpClient

Triplit provides helpful abstractions for interacting with the HTTP API. Read more about it in the Triplit Client documentation.

Routes

/fetch

Performs a fetch, returning the an array of entities that meet the query criteria.

// Request
await fetch('https://<project-id>.triplit.io/fetch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
  body: JSON.stringify({
    collection: 'todos',
    query: {
      collectionName: 'todos',
      where: [['completed', '=', false]],
    },
  }),
});
 
// Response
[
  {
    id: '123',
    title: 'Buy milk',
    completed: false,
  },
  {
    id: '456',
    title: 'Buy eggs',
    completed: false,
  },
];

/insert

Inserts a single entity for a given collection.

// Request
await fetch('https://<project-id>.triplit.io/insert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
  body: JSON.stringify({
    collectionName: 'todos',
    entity: {
      id: '123',
      title: 'Buy milk',
      completed: false,
    },
  }),
});

/bulk-insert

Inserts several entities at once that are provided as an object where the collection names are the keys and the list of entities for that collection are the values.

// Request
await fetch('https://<project-id>.triplit.io/bulk-insert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
  body: JSON.stringify({
    todos: [
      {
        id: '123',
        title: 'Buy milk',
        completed: false,
      },
      {
        id: '456',
        title: 'Buy eggs',
        completed: false,
      },
    ],
  }),
});

/update

Updates a single entity for a given collection with a set of provided patches.

// Request
await fetch('https://<project-id>.triplit.io/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
  body: JSON.stringify({
    collectionName: 'todos',
    entityId: '123',
    patches: [
      ['set', 'completed', true],
      ['set', 'title', 'Buy milk and eggs'],
    ],
  }),
});

/delete

Deletes a single entity for a given collection.

// Request
await fetch('https://<project-id>.triplit.io/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
  body: JSON.stringify({
    collectionName: 'todos',
    entityId: '123',
  }),
});

/delete-all

Deletes all entities for a given collection.

// Request
await fetch('https://<project-id>.triplit.io/delete-all', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + TRIPLIT_TOKEN,
  },
  body: JSON.stringify({
    collectionName: 'todos',
  }),
});

/healthcheck

This endpoint is publicly available (i.e. no authentication token is required) and will return a 200 status code if the server is running and healthy.

Server-side rendering