Open Orbit

Apps

Understand an Orbit app's organization, identifier, name, settings, and languages, and how API access affects app lists.

An Orbit app is a project within an organization, with its own identifier, name, settings, themes, and language configuration.

An app belongs to an organization

Each app has an org_id that identifies its organization. The Orbit API specification defines that relationship as fixed: you cannot transfer an app between organizations through the API.

For example, a task tracker and a customer directory can be two apps in the same organization. These example names describe separate projects, not two pages within one app.

The identifier is not the name

An app has three distinct values:

  • id: the stable UUID used in API request paths.
  • title: the name people see. The API accepts 1 to 200 characters.
  • slug: an identifier unique within the organization. It contains 1 to 60 lowercase letters, digits, or hyphens.

For the example task tracker, the title could be Team tasks and the slug could be team-tasks. Use the app's actual id, not either name, when an API request requires an app UUID.

The app also has an optional description and an icon. A title tells people which project they opened; the UUID tells the API which project a request addresses.

Configuration belongs to the app

The API exposes these app-level values:

  • settings: a free-form settings map. The specification says tools should treat this map as opaque.
  • themes: the theme catalog, with active theme and definition values.
  • locales: the authored language, other available languages, and a glossary of names that translators must not translate.

A list of configured languages is not a translation report. The API provides translation information separately at GET /api/v1/apps/{app_id}/translations.

Access changes which apps you see

GET /api/v1/apps returns the apps the calling token can read:

  • A profile-scoped token can list apps across organizations where the caller has an active membership.
  • An organization-scoped token lists apps only within its bound organization.

The optional org_id query parameter restricts the list to one organization. An organization the caller cannot see produces an empty data array, not an HTTP 403 response.

An empty list therefore does not prove that an organization has no apps. Check the token's scope and organization access before you draw that conclusion.

Next steps

Build your first app to create a project. If you already have an app, define a data model for the records it needs.