Instant features

Admin HTTP API

If your backend is written in Javascript, you can use the @instantdb/admin SDK to connect your server to Instant.

But what if your backend isn't written in Javascript? That's where the HTTP API comes in.

You can use the HTTP API in your favorite backend language to run scripts, create custom auth flows, or evaluate sensitive app logic.

If you give this documentation to your AI agent, it can create a custom SDK for your backend language. Here's the markdown.

#Auth

First and foremost, grab your app's APP_ID and ADMIN_TOKEN. You can get this by going to your dashboard. To authenticate requests, include them in your HTTP headers:

curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"goals":{}}}'

#Reading and Writing Data

POST /admin/query and POST /admin/transact let your read and write data as an admin.

#query

To make queries, run POST /admin/query with an InstaQL query:

curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"goals":{},"todos":{}}}'

If you need rule params, include $$ruleParams at the top-level:

{
  "$$ruleParams": { "knownGoalId": "..." },
  "query": { "goals": {} }
}

As a refresher, you can learn about InstaQL queries here.

#transact

To make transactions, send POST /admin/transact with steps:

curl -X POST "https://api.instantdb.com/admin/transact" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"steps":[["update","todos","<a-todo-uuid>",{"title":"Get fit"}]]}'

steps is the internal representation of Instant transactions. Here's how they map to the Instant transactions you know:

[
  // tx.goals[goalId1].update({title: "moop"})
  [
      "update",
      "goals",
      goalId1,
      {
          "title": "moop"
      }
  ],
  // tx.goals[goalId1].link({todos: todoId1})
  [
      "link",
      "goals",
      goalId1,
      {
          "todos": todoId1
      }
  ],
  // tx.goals[goalId1].unlink({todos: todoId1})
  [
      "unlink",
      "goals",
      goalId1
      {
          "todos": todoId1
      }
  ],
  // tx.goals[goalId1].delete()
  [
      "delete",
      "goals",
      goalId1
  ],
]

#Subscriptions on the backend

You can subscribe to queries over SSE with POST /admin/subscribe-query.

The connection stays open and streams updates.

curl -N -X POST "https://api.instantdb.com/admin/subscribe-query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"tasks":{}}}'

Subscriptions keep a live connection open on your backend. Be sure to close them when they are no longer needed.

#Impersonating users

When you use the admin API, you can make any query or transaction. As an admin, you bypass permissions.

But sometimes you want to make requests on behalf of a user and respect permissions. You can do this by passing the As-Email, As-Token, or As-Guest headers.

# Scoped by their email
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Email: alyssa_p_hacker@instantdb.com" \
  -d '{"query":{"goals":{}}}'
 
# Or with their auth token
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Token: $REFRESH_TOKEN" \
  -d '{"query":{"goals":{}}}'
 
# Or use the db as a guest
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Guest: true" \
  -d '{"query":{"goals":{}}}'

As-Email requires an ADMIN_TOKEN. For As-Token and As-Guest, you could skip the Authorization if you want too.

#Retrieve a user

Use GET /admin/users to fetch an app user by email, id, or refresh_token.

# By email!
curl -X GET "https://api.instantdb.com/admin/users?email=alyssa_p_hacker@instantdb.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
 
# By id
curl -X GET "https://api.instantdb.com/admin/users?id=$USER_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
 
# Or by a refresh token
curl -X GET "https://api.instantdb.com/admin/users?refresh_token=$REFRESH_TOKEN" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

#Delete a user

Use DELETE /admin/users to delete an app user by email, id, or refresh_token.

# By email
curl -X DELETE "https://api.instantdb.com/admin/users?email=alyssa_p_hacker@instantdb.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
 
# By id
curl -X DELETE "https://api.instantdb.com/admin/users?id=$USER_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
 
# Or by an auth token
curl -X DELETE "https://api.instantdb.com/admin/users?refresh_token=$REFRESH_TOKEN" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

#Presence in the Backend

If you use rooms & presence, you may want to query for the data currently in a room. This can be especially useful if you are sending a notification for example, and want to skip it if the user is already online. To do get room data use GET /admin/rooms/presence. Make sure to pass in a room-type and a room-id:

curl -X GET "https://api.instantdb.com/admin/rooms/presence?room-type=chat&room-id=room-123" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

#Sign Out

POST /admin/sign_out allows you to log out users. You can log out a user out from every session by passing in their email or id. Or you can log a user out from a particular session by passing in a refresh_token:

# All sessions for this email sign out
curl -X POST "https://api.instantdb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'
 
# All sessions for this user id sign out
curl -X POST "https://api.instantdb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"id\":\"$USER_ID\"}"
 
# Just sign out the session for this refresh token
curl -X POST "https://api.instantdb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}"

#Custom Auth

You can use POST /admin/refresh_tokens to generate auth tokens for your users.

Pass in an email or an id to create a refresh token:

# By email
curl -X POST "https://api.instantdb.com/admin/refresh_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'
 
# Or by ID
curl -X POST "https://api.instantdb.com/admin/refresh_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"id\":\"$USER_ID\"}"

If a user with the provider id or email does not exist, Instant will create the user for you. The response includes user.refresh_token. You can pass this token onto your client, and use that to log in

#Custom magic codes

We support a magic code flow out of the box. However, if you'd like to use your own email provider to send the code, you can create a magic code with POST /admin/magic_code:

curl -X POST "https://api.instantdb.com/admin/magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'

You can also use Instant's default email provider to send a magic code:

curl -X POST "https://api.instantdb.com/admin/send_magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'

Similarly, you can verify a magic code too:

curl -X POST "https://api.instantdb.com/admin/verify_magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com","code":"123456"}'

#Authenticated Endpoints

To authenticate users, have your frontend pass in a refresh token. Then use POST /runtime/auth/verify_refresh_token to verify it:

curl -X POST "https://api.instantdb.com/runtime/auth/verify_refresh_token" \
  -H "Content-Type: application/json" \
  -d "{\"app-id\": \"$APP_ID\", \"refresh-token\": \"$REFRESH_TOKEN\"}"

#Storage

You can also manage your app's storage with the HTTP API.

#Upload Files

Upload a file with PUT /admin/storage/upload:

curl -X PUT "https://api.instantdb.com/admin/storage/upload" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "Path: snippets/demo.txt" \
  -H "Content-Type: text/plain" \
  --data-binary "@demo.txt"

#Delete Files

Delete a file by path:

curl -X DELETE "https://api.instantdb.com/admin/storage/files?filename=snippets/demo.txt" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

Delete multiple files by path:

curl -X POST "https://api.instantdb.com/admin/storage/files/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"filenames":["snippets/1.txt","snippets/2.txt"]}'

#List Files

List files by querying $files:

curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"$files":{}}}'

Previous: Storage
Next: (Experimental) Next.js SSR