API Reference

You do not need this section to build with Instroc. Roc writes your app's code, wires it to your database, accounts, files, and functions, and keeps it working as your app grows. If you build entirely in chat, you can skip this section and get more value from Prompting best practices.

This reference is for the moments you look under the hood: you open the code editor and want to know what a line does, you want to tweak something by hand, or you want another system to talk to your app's backend. It documents the building blocks Roc uses, so what you find in your code is never a mystery.

info

Everything here describes code inside your app. You never install anything or set up a project by hand; every Instroc app already has all of this built in.

How your app talks to its backend

Your app's code uses a small set of ready-made hooks, grouped into four packages you will see in import lines: @instroc/client, @instroc/auth, @instroc/data, and @instroc/functions. A hook is one line in a component: call useQuery("tasks") and you have live rows from your tasks table, call useAuth() and you know who is signed in.

Zero setup, by design

There is nothing to configure in your app code. The SDK's configuration is injected at build time, so your app never calls an initInstroc() function and never wraps the tree in a provider component. You import a hook, call it in a component, and it works.

Sessions are handled the same way. When a user signs in, the SDK stores the session in secure HttpOnly cookies and refreshes it automatically. Tokens are never written to localStorage, and your code never touches them.

Your project's public key (the one you see in Cloud under API & Secrets) is safe to ship in the browser. It works like a publishable key: it identifies your project, and the security rules on each table decide what any given caller can actually read or write. See Security rules for how that works.

A quick taste

Here is a small component that uses all three main packages together: it reads the signed-in user, queries a table, and inserts a row.

import { useAuth } from "@instroc/auth";
import { useQuery, useMutation } from "@instroc/data";

function TaskBoard() {
  const { user } = useAuth();
  const { data: tasks, loading } = useQuery("tasks", {
    order: "created_at:desc",
    limit: 20,
  });
  const { insert, isPending } = useMutation("tasks");

  if (loading) return <p>Loading...</p>;

  return (
    <div>
      <p>Signed in as {user?.email}</p>
      <button
        disabled={isPending}
        onClick={() => insert({ title: "New task", done: false })}
      >
        Add task
      </button>
      <ul>
        {tasks.map((t) => (
          <li key={t.id}>{t.title}</li>
        ))}
      </ul>
    </div>
  );
}

Notice what is missing: no client instance, no API key in code, no manual refetch after the insert. Successful mutations automatically refresh queries on the same table.

Where to find what

The reference is organized by package and concern. Each page includes full signatures and realistic examples.

Page	Covers
Data	useQuery, useLazyQuery, useInfiniteQuery, useMutation, error handling
Authentication	useAuth, OAuth, route guards, form hooks, the AuthUser shape
Storage	File upload, listing, deletion, and URLs (these hooks live in @instroc/data)
Functions	useFunction, template functions, the inbox sendMessage helper
Filters	Every filter operator, ordering, and pagination
Security rules	Table visibility levels and what each caller is allowed to do

The HTTP API

Everything the SDK does goes over a plain HTTP API, and external callers (scripts, other services, tools like curl) can use it directly. The base URL is:

/api/baas/{projectId}

Authenticate with a bearer header carrying your project's public key: Authorization: Bearer <key>. End-user identity, when present, comes from the secure session cookie. The main route families are:

• GET/POST/PATCH/DELETE /data/:table with query params select, filter, order, limit, offset
• POST /data/:table/batch for up to 100 items per call, GET /data/:table/export?format=csv|json, and POST /data/:table/aggregate for count, sum, avg, min, and max
• POST /auth/login, /auth/signup, /auth/logout, /auth/refresh, plus GET /auth/me, GET /auth/config, and the verification and password-reset endpoints
• POST /storage/upload (multipart, 50 MB max), GET /storage/files, and per-file get, patch, delete, and download routes
• POST /functions/:name/invoke to run a serverless function
• POST /messages to send an inbox message

Responses use a consistent envelope. Reads return {data: [...], count}, writes return {data, count} or {count}, and failures return {error}.

What does not exist

The SDK is deliberately small. There are no realtime subscription hooks, no include or relationship joins on queries, no magic link sign-in, and no separate @instroc/storage package (storage hooks live in @instroc/data). If you see code or docs elsewhere referencing any of these, it is wrong.

Related pages

For the product-level view of the backend (enabling Instroc Cloud, managing tables in the editor, webhooks), start with the Backend overview. For custom server-side endpoints inside your app, see API routes.