Connect an app to the database

You need a SQL table. posts with an id and a title is enough. You also need an API key on that SQL connector. Create it under Workspace settings, API Keys, if the action reports that the key is missing. You do not paste the key into the app. The action reads it from orbi.project.apiKeys.

1. Open the app.
2. Add a server action named list_posts.
3. Replace the code with the sample.
4. Save, then run the action.

You should see an array of rows. An empty array means the table has no rows yet.

async ({ orbi }) => {
  const apiKey = orbi.project.apiKeys.find((key) => key.connectorId)
  if (!apiKey) throw new Error("Create an API key for the database under Workspace settings, API Keys.")
  const response = await fetch("https://core.orbitype.com/api/sql/v1?sql=" + encodeURIComponent("SELECT id, title FROM posts ORDER BY id"), {
    headers: { "X-API-KEY": apiKey.key },
  })
  if (!response.ok) throw new Error(await response.text())
  return await response.json()
}

Apps are pages you create inside Orbitype. They are ideal for public forms, pricing calculators, internal tools, dashboards, and custom data experiences.

What an app includes

• Title: clear name of your app

• Description: context for teammates and users

• HTML: the UI rendered in the live preview

• Actions: backend functions called from the UI

• Visibility: private or public

Why use apps

• Fast delivery for custom pages and calculators

• Built-in connection to Orbitype runtime

• Easy share and embed workflow

• No extra hosting setup for basic use cases

Step-by-step

1. Open Apps in the sidebar.
2. Click New app.
3. Add title and description.
4. Build your interface in the HTML editor.
5. Use the live preview to test behavior.
6. Save and iterate.

Typical examples

• Lead intake form with validation
• ROI or pricing calculator
• Campaign performance calculator
• Interactive onboarding checker

Editor tips

• Keep each app focused on one primary user task
• Use clear labels and empty states
• Design for mobile first if shared externally

Use actions when your form or calculator needs secure server-side logic (database queries, APIs, AI calls, enrichment, etc.).

Call an action from your app

const result = await Orbi.action("load_kpis", { range: "30d" })
console.log(result)

Action model

• name: unique identifier used by Orbi.action(...)
• code: server-side function logic
• input: payload sent from UI
• output: returned result for rendering

Recommended output shape

{
  "ok": true,
  "data": { ... },
  "error": null
}

Stable response structures make frontend rendering and error handling easier.

Visibility

• Private: only accessible inside your workspace context
• Public: accessible via public link

Sharing options

• Open the public page URL
• Copy the embed iframe snippet
• Embed in external sites or docs

Before switching to public

• Test the full user flow
• Check empty states and errors
• Review text, labels, and mobile layout
• Ensure no internal-only data is exposed

• Start with one concrete outcome per app
• Keep business logic in actions, not in UI scripts
• Use explicit action names (calculate_offer, submit_lead)
• Return consistent JSON shapes
• Gracefully handle loading, empty, and error states

Common issues

• Action not found: verify action name matches exactly.
• No data in UI: check that action returns expected JSON fields.
• Runtime error: validate input and wrap risky logic in try/catch.
• Public link fails: verify visibility is set to public.

Create an API key means no key is stored for a connector. Create one on the SQL connector. relation posts does not exist means the table name is different. Change posts to your table.