--- title: "Create an app" description: "Create an app at the suite's address followed by its slug." canonical: "https://grid82.com/docs/builder-api/apps/create" updated: "2026-11-13" --- # Create an app `POST https://studio.grid82.app/v1/apps` Create an app at the suite's address followed by its slug. The builder is not automatically a member; no role has special platform privileges. Starts with `Role 1`, full access to all tables and no members: rename it and narrow access with `rules.set` before adding anyone. Without `tables`, creates a sample `Project` table and rows. Supply `tables` for your own structure; each field is `{ name, type, config? }`, and `fields.types` lists the settings each type takes. Requires the `schema:write` scope. Operation `apps.create`. MCP tool `apps_create`. CLI: `grid82 apps create` (`npx grid82`). ## Headers | Name | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Idempotency-Key` | string | no | Any unique string. Sending the same key with the same request again returns the first response (marked `Idempotency-Replayed: true`) instead of running it twice. Reusing it for a different request is refused with 409. Kept for 24 hours. Up to 255 characters. | ## Request body | Field | Type | Required | Description | | --------- | --------- | -------- | -------------------- | | `suiteId` | string | yes | Up to 64 characters. | | `name` | string | yes | Up to 50 characters. | | `slug` | string | no | | | `tables` | object\[] | no | | **Authorizations** - `Authorization` (bearer, in header, required) ## Response **201**: Success - `data` (`object`, required) - `data.schemaVersion` (`number`, required) - `data.id` (`string`, required, length: `1–64 chars`) - `data.name` (`string`, required, length: `1–120 chars`) - `data.slug` (`string`, required, pattern: `^[a-z0-9][a-z0-9-]{1,62}$`) - `data.tables` (`object[]`, required, items: `≤ 200 items`) - `data.tables.id` (`string`, required, pattern: `^[a-z][a-z0-9_]{0,62}$`) - `data.tables.name` (`string`, required, length: `1–120 chars`) - `data.tables.plural` (`string`, length: `1–120 chars`) - `data.tables.description` (`string`, length: `≤ 2000 chars`) - `data.tables.icon` (`string | null`) - `data.tables.primaryFieldId` (`string`, required, pattern: `^[a-z][a-z0-9_]{0,62}$`) - `data.tables.fields` (`object[]`, required, items: `1–200 items`) - `data.tables.fields.id` (`string`, required, pattern: `^[a-z][a-z0-9_]{0,62}$`) - `data.tables.fields.name` (`string`, required, length: `1–120 chars`) - `data.tables.fields.width` (`integer`, range: `60–900`) - `data.tables.fields.type` (`string`, required) - `data.tables.fields.config` (`object`, required, default: `{}`) - `data.views` (`Record`, required, default: `{}`) - `data.rules` (`object`, required) - `data.rules.version` (`number`, required) - `data.rules.roles` (`object[]`, required, items: `1–100 items`) - `data.rules.roles.id` (`string`, required, pattern: `^[a-z][a-z0-9_]{0,62}$`) - `data.rules.roles.name` (`string`, required, length: `1–120 chars`) - `data.rules.roles.description` (`string`, length: `≤ 500 chars`) - `data.rules.roles.assistantMonthlyCredits` (`integer`, range: `0–10000000`) - `data.rules.roles.interface` (`enum`, one of: `assigned, own`) - `data.rules.roles.automations` (`enum`, one of: `none, own`) - `data.rules.permissions` (`object[]`, required, items: `≤ 100 items`) - `data.rules.permissions.role` (`string`, required, pattern: `^[a-z][a-z0-9_]{0,62}$`) - `data.rules.permissions.tables` (`string | Record`, required) - `data.pages` (`object[]`, required, default: `[]`) - `data.pages.id` (`string`, required, length: `1–64 chars`) - `data.pages.name` (`string`, required, length: `1–120 chars`) - `data.pages.kind` (`enum`, required, one of: `declarative, code`) - `data.pages.mode` (`enum`, required, one of: `locked, template, canvas`) - `data.pages.owner` (`enum`, required, one of: `admin, user`) - `data.pages.ownerUserId` (`string`, length: `≤ 64 chars`) - `data.pages.tableId` (`string`, pattern: `^[a-z][a-z0-9_]{0,62}$`) - `data.pages.forkedFrom` (`string`, length: `≤ 64 chars`) - `data.pages.visibleTo` (`string | string[]`, required, default: `*`) - `data.pages.reads` (`object`) - `data.pages.reads.tables` (`string[]`, required, default: `[]`) - `data.pages.reads.fields` (`string[]`, required, default: `[]`) - `data.pages.reads.views` (`string[]`, required, default: `[]`) - `data.pages.bundleHash` (`string`, length: `≤ 128 chars`) - `data.pages.publishedVersion` (`integer`, range: `≥ 1`) - `data.pages.theme` (`object`) - `data.pages.theme.accent` (`string`, pattern: `^(?:#[0-9a-fA-F]{3,8}|oklch\([0-9.%\s/]{1,60}\))$`) - `data.pages.theme.radius` (`number`, range: `0–24`) - `data.pages.document` (`object`) - `data.pages.version` (`integer`, required, default: `1`, range: `≥ 1`) - `data.pages.updatedAt` (`string`, required) - `data.members` (`object[]`, required, default: `[]`) - `data.members.userId` (`string`, required, length: `1–64 chars`) - `data.members.email` (`string`, required, pattern: `^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`) - `data.members.name` (`string`, length: `≤ 120 chars`) - `data.members.roles` (`string[]`, required, items: `≥ 1 items`) - `data.members.status` (`enum`, required, default: `invited`, one of: `invited, active, suspended`) - `data.members.invitedAt` (`string`) - `data.theme` (`object`, required, default: `{"radius":6,"accent":"oklch(0.47 0.16 262)","font":"inter"}`) - `data.theme.radius` (`number`, required, default: `6`, range: `0–24`) - `data.theme.accent` (`string`, required, default: `oklch(0.47 0.16 262)`, pattern: `^(?:#[0-9a-fA-F]{3,8}|oklch\([0-9.%\s/]{1,60}\))$`) - `data.theme.font` (`enum`, required, default: `inter`, one of: `system, geist, inter, figtree, manrope, jakarta, dm-sans, outfit, work-sans, nunito-sans, rubik, public-sans, source-serif, lora, fraunces, instrument-serif, geist-mono, jetbrains-mono, ibm-plex-mono`) - `data.theme.icon` (`string | null`, default: `null`) - `data.surfaces` (`object`, required, default: `{"data":true,"interface":true,"assistant":true,"api":true,"mcp":true,"cli":true}`) - `data.surfaces.data` (`boolean`, required, default: `true`) - `data.surfaces.interface` (`boolean`, required, default: `true`) - `data.surfaces.assistant` (`boolean`, required, default: `true`) - `data.surfaces.api` (`boolean`, required, default: `true`) - `data.surfaces.mcp` (`boolean`, required, default: `true`) - `data.surfaces.cli` (`boolean`, required, default: `true`) - `data.updatedAt` (`string`, required) ```json { "data": { "schemaVersion": 123.45, "id": "", "name": "", "slug": "", "tables": [ { "id": "", "name": "", "plural": "", "description": "", "icon": "", "primaryFieldId": "", "fields": [ { "id": "", "name": "", "width": 123, "type": "", "config": {} } ] } ], "views": {}, "rules": { "version": 123.45, "roles": [ { "id": "", "name": "", "description": "", "assistantMonthlyCredits": 123, "interface": "assigned", "automations": "none" } ], "permissions": [ { "role": "", "tables": "" } ] }, "pages": [], "members": [], "theme": { "radius": 6, "accent": "oklch(0.47 0.16 262)", "font": "inter" }, "surfaces": { "data": true, "interface": true, "assistant": true, "api": true, "mcp": true, "cli": true }, "updatedAt": "" } } ``` **4XX**: Refused - `error` (`object`, required) - `error.code` (`enum`, required, one of: `not_found, forbidden, unauthenticated, validation_failed, conflict, rate_limited, payment_required, not_implemented, internal`) - `error.message` (`string`, required) - `error.details` (`Record`) ```json { "error": { "code": "not_found", "message": "", "details": {} } } ``` **Example request** ```bash curl --request POST \ --url 'https://studio.grid82.app/v1/apps' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "suiteId": "", "name": "" }' ```