Playground and API Reference
Two pages in the app's console: API Reference shows every model, field and action of an environment as its files define them now, and Playground runs a call against it as a store and a role, with the call as code to copy.
API Reference
API Reference in the app's console is worked out from the environment's files: each model with its fields, their types, the filter operators each takes, whether it sorts and joins text search, and its description; who may read it, from accessControl/permissions.ib.ts; each action with its params (as written and as JSON Schema), whether it works on a record, who may call it, and the webhook topic or schedule in settings.ib.ts that queues it. Development's changes as a schema or action file changes; production's shows what the last deploy carried, and is empty until the first.
Beside each model and action, the call as code with Copy: SDK (the app's api client), curl, fetch, and MCP (the tool call an agent would make), plus Try in Playground, which opens the Playground with that call ready. The page's header has Copy as Markdown, JSON and OpenAPI, and Open Playground.
One source
The page is one view of a reference every environment has, and everything that describes the app's API reads the same files the same way, so they can't disagree:
| Where | What |
|---|---|
| The console's API Reference page | The reference, with code to copy and Try in Playground. |
GET …/reference | The reference as JSON. |
GET …/reference.md | The reference as Markdown, for a README or an agent's context: the same text as Copy as Markdown. |
GET …/openapi.json | The environment's API as OpenAPI 3.1: the records routes per model, every action, the record and input schemas, and the headers the API takes. |
| The MCP server | get_reference returns the Markdown, whole or for one model; list_models and list_actions are its parts. |
| The generated types | web/ib-client.d.ts and the CLI's types read the same schemas and params, so what the reference lists is what api and the hooks are typed with. |
| The Playground | Its list of calls and the completion in its editor. |
# The same reference the page shows, for an agent's context or a README.
curl https://api.inferencebureau.com/v1/apps/ib-reviews/environments/development/reference.md \
-H "Authorization: Bearer $IB_API_KEY"
# As OpenAPI 3.1, for Zapier, n8n, ChatGPT actions or openapi-typescript.
curl https://api.inferencebureau.com/v1/apps/ib-reviews/environments/production/openapi.json \
-H "Authorization: Bearer $IB_API_KEY"The routes take a project key with Apps Permissions or the environment's token; … is /v1/apps/<app>/environments/<env>. See API and keys.
Descriptions
A description on a schema, a field, a param or an action's options is what the reference shows for it, everywhere above. Without one, the reference still describes types, filters, grants and triggers; with them, an agent reading reference.md or calling get_reference knows what a field means and when to call an action.
// api/models/review/schema.ib.ts
export const schema: ModelSchema = {
type: "ib/model-schema/v1",
description: "A customer's review of a product, moderated before it's shown.",
fields: {
rating: { type: "number", description: "1 to 5 stars.", validations: { required: true, range: { min: 1, max: 5 } } },
status: { type: "enum", options: ["pending", "approved", "rejected"], description: "Only approved reviews show on the storefront." },
},
};
// api/models/review/actions/approve.ts
export const params = { note: { type: "string", description: "Why, for the audit trail." } };
export const options: ActionOptions = { description: "Publishes the review and tells the customer." };Playground
Playground runs one call against the environment's records API, as the API would answer it: pick a model and a call (findMany, findFirst, findOne, create, update, delete, or one of the model's actions with run), or a global action; write its JSON in an editor that completes and checks against the environment's schemas and the action's params; choose a record by id from the records it suggests; and run it. The answer shows as JSON or, for records, as a table, with a link to the call's event in Logs. Beside the answer, the same call as SDK, curl and fetch code to copy into the app or a script.
- Reads are open to anyone who can see the app. Writes and actions need Edit on it, as Run action in Files does;
create,updateanddeleterun the model's action when it has one, and the call is an event in Logs with you as its actor. - An action run waits for the run to finish, up to its 15 minutes. In development, a sleeping dev server is started first.
- The call being written is kept in the browser as you type, so a reload brings it back. Production has no records until the first deploy; the page offers development's meanwhile.
Running as a store and a role
By default a call has the environment token's full access, as the app's own createClient() has. Run as narrows it to what a page or an extension would get: a role from permissions.ib.ts, with the userId, customerId or customer record a filter's $session stands for, and, in a Shopify app, a store the environment is installed on, so the call reaches only that store's records. That is how to check a grant before writing the page that relies on it: run findMany as signed-in with a user's id and see what comes back. A permissions file that can't be read is named on the page. See Access control.
A call run as a role is held to that role's grants as the records route holds a page: what the page would be refused, the Playground refuses too, with the reason.
History
Every run lands in your history for the environment, kept on the server, so a reload or another computer has it: the call as it was sent (the editor's text, never more), its status, how long it took, and its event. The newest 200 unsaved calls are kept; name a call to keep it for good, and open any entry to run it again. Forget removes one, or every unsaved call. History is yours, not the team's: each person's calls are their own.