App catalog

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.

These operations are available with supported self-hosted and Cloud providers. A fixed organization scope requires a direct compatible Cloud connection; see Cloud compatibility.

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>

On self-hosted destinations, this compares the machine with the app's minResources recommendation. On Openship Cloud, it previews the workspace allocation against the current plan. Pass projectId to include a draft's saved resource settings; access to that project is required.

{
  "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 }
    }
  }
}

A server ID must be accessible in the current organization. Cloud targets and machines that cannot be probed can report capacity.source: "unknown" with fit.ok: true; that means no measured capacity comparison was available, not that the host capacity was verified.

Install an app

For a template app, installation creates or updates a project draft and returns projectId. Submit a deployment for that project to run it. A flow app returns flowHref for its setup wizard.

const result = await ship.apps.install({
  templateId: "ghost",
  name: "my-blog",
  routes: [
    {
      service: "ghost",
      port: 2368,
      mode: "custom",
      customDomain: "blog.acme.com",
    },
  ],
});
console.log(result);

curl -X POST "$OPENSHIP_URL/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" }
    ]
  }'

Each routes entry:

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 operation table apply unchanged. What that means in practice:

Errors

Related guides

• 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

Operations

Connections, storage, and apps

Resource methods