Apps API

An app is a JSON definition that installs a set of containers as a project in one click — with its images, wiring, generated secrets, curated settings form, and connection card already described. This API covers browsing the catalog, installing, adding your organization's own custom apps, and reading or updating an installed app afterwards.

In the dashboard this is the Apps tab. The definition format is documented in the App catalog JSON reference, and authoring workflow in Add an app.

Endpoints

List the catalog

GET /api/apps/catalog

The runtime catalog is the copy bundled in your build, overlaid by a live fetch of the curated catalog from the Openship repo (refreshed on a 10-minute TTL, stale-while-revalidate), plus your organization's custom apps. A failed fetch or an offline instance simply keeps serving the last-good copy, so the overlay can never break the catalog.

Because the overlay can be ahead of your instance, entries carry compatibility flags:

Each entry also carries hosting ("experimental" marks a stack that runs but is heavy or not production-grade upstream) and, for the few apps that declare one, minResources — the host floor you can check with host-fit before installing. Apps marked unlisted are absent from this list by design: they stay installable by id, reached through another app's wizard.

Get one app

GET /api/apps/catalog/:id

Returns the full definition — services, config fields, endpoints, settings, connection. Curated apps win over custom ones: a custom app can never shadow a verified id (also enforced at upload).

This is config metadata only, never secrets — generated values are minted at install, so nothing sensitive exists to return yet.

The response also carries a draft alongside data: this organization's open, never-deployed draft of the same app, if one exists.

Check a destination

GET /api/apps/catalog/:id/host-fit?deployTarget=server&serverId=<id>

Does a machine meet what the app declares in minResources? Ask before installing, so the operator sees the shortfall instead of discovering it from a failed deploy.

{
  "data": {
    "minResources": { "memoryMb": 8192, "cpuCores": 4 },
    "capacity": { "cpuCores": 2, "memoryMb": 2048, "source": "docker" },
    "fit": {
      "ok": false,
      "memory": { "needed": 8192, "available": 2048 },
      "cpu": { "needed": 4, "available": 2 }
    }
  }
}

An id from another organization, a target of cloud, or a machine that cannot be probed all return fit: { "ok": true } with capacity.source: "unknown" — the same "nothing to enforce" answer, so a client has one shape to handle.

Install an app

POST /api/apps

For a template app this creates the project and starts the deploy. For a flow app it returns the route of that app's bespoke wizard instead of installing anything.

Each routes entry:

curl -X POST https://your-host/api/apps \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "ghost",
    "name": "my-blog",
    "routes": [
      { "service": "ghost", "port": 2368, "mode": "custom", "customDomain": "blog.acme.com" }
    ]
  }'

Custom apps

POST   /api/apps/custom
GET    /api/apps/custom
DELETE /api/apps/custom/:appId

POST accepts a full app definition as the request body. The body is gated here only as "must be a JSON object" — the authoritative validation runs in the service and is the same strict check as the curated catalog, shape plus every referential rule.

Four constraints are enforced:

• Always unverified. verified and available are set by the server, so a file claiming "verified": true is ignored.
• kind must be template. Flow apps are rejected.
• The id cannot shadow a built-in app.
• Validation errors are returned with the offending detail, including a distinct message when the definition targets a newer catalog schemaVersion than the instance supports.

A custom app installs through the normal services pipeline with the same in-container boundary as any project you deploy yourself — no new privilege.

Curated settings

GET   /api/projects/:id/app-settings
PATCH /api/projects/:id/app-settings

GET returns the app's settings schema together with current values, so a client can render the form without knowing the app. PATCH applies a safe env merge — only the keys you send are touched:

Empty-string semantics differ by field kind, which matters when a form re-submits untouched inputs:

Fields marked requiresRedeploy in the definition take effect only after a redeploy; the response and the dashboard both surface that.

Connection details

GET /api/projects/:id/app-connection

Resolves the app's connection outputs against the running services — public URLs, generated keys, composed connection strings — and returns them ready to use, including any labeled variants such as a public versus internal-network form.

MCP exposure

Every route in this module is also exposed as an MCP tool, so an AI agent can browse the catalog, install an app, and read its settings and connection details. Tool exposure is an opt-in allowlist — a route becomes a tool only when its spec declares an mcp block — and the module-level hard-deny list covers only tokens, auth, and mcp. apps is not on it.

Every MCP call re-checks the caller's permissions, so the tags in the endpoints table apply unchanged. What that means in practice:

Errors you might see

See also

• App catalog JSON — every field in an app definition
• Add an app — submit a curated app, or upload a custom one
• Services API — the services an installed app is made of
• Projects API — the project an app installs into