Apps

Manage your apps and versions via REST.

For running apps (creating tasks), see Tasks. For CLI deploy workflows, see Deploying.

→ Apps concept · Extending Apps

Authentication

Read endpoints require the apps:read scope. Write endpoints (including setting the current version) require apps:write.

Get App

GET /apps/{id}

Returns a single app by ID, including the active version in version_id and version.

GET /apps/{namespace}/{name}

Returns an app by namespace and name (for example myteam/my-app).

Returns 404 with code not_found when no app matches. Version 1 responses may include error.suggestions with up to three similar public app refs (same name in other namespaces, or similar names in the same namespace). Version 2 returns not_found without suggestions — use Search for broader discovery.

List Apps

GET /apps or POST /apps/list

Returns your apps with cursor-based pagination. Requires the apps:read scope.

Request

Supported filter and sort fields include namespace, name, category, visibility, created_at, and updated_at. Unknown filter or sort columns return 400 (Invalid sort or filter field). See Cursor pagination.

Text search: search.term is required. Each name in search.fields must be an allowlisted column (namespace, name, description, category, agent_description, and others on the app model). Invalid or empty field names are ignored; if no valid fields remain, the search clause is skipped.

Example — filter by namespace:

1curl -X POST https://api.inference.sh/apps/list \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Content-Type: application/json" \5  -d '{6    "limit": 20,7    "filters": [{ "field": "namespace", "operator": "eq", "value": "myteam" }]8  }'

Example — search name and description:

1curl -X POST https://api.inference.sh/apps/list \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Content-Type: application/json" \5  -d '{6    "limit": 20,7    "search": { "term": "flux", "fields": ["name", "description"] }8  }'

Response

List Versions

GET /apps/{id}/versions or POST /apps/{id}/versions/list

Returns version history for an app. Each version has its own ID.

Get Version

GET /apps/{id}/versions/{versionId}

Returns a specific app version. versionId is the version's ID (the segment after @ in refs like myteam/my-app@ver_abc123).

Set Current Version

PUT /apps/{id}/versions/{versionId}/current

Sets which version is active for the app. The active version is what runs when callers use namespace/name without @version, and what the Grid and search index expose as the live app.

Requires the apps:write scope. No request body. Idempotent: calling it again with the same version has no effect.

Example

1curl -X PUT "https://api.inference.sh/apps/app_abc123/versions/ver_xyz789/current" \2  -H "Authorization: Bearer inf_your_key"

Response

Returns the updated app (same shape as Get App), with version_id and version pointing at the promoted version.

1{2  "id": "app_abc123",3  "namespace": "myteam",4  "name": "my-app",5  "version_id": "ver_xyz789",6  "version": { "id": "ver_xyz789", "kernel": "python-3.11" }7}

When to use this

• After a staged deploy (infsh app deploy --stage) — promote the new version when you are ready
• To roll back — set an older version as current
• From automation — switch active versions without using the web UI

By default, infsh app deploy (without --stage) makes the new version current automatically. Use staged deploys plus this endpoint when you want to test a version before promoting it.

Migration from POST /apps/{id}/current-version

The previous endpoint accepted the version ID in the JSON body:

1# Removed — do not use2curl -X POST "https://api.inference.sh/apps/app_abc123/current-version" \3  -H "Authorization: Bearer inf_your_key" \4  -H "Content-Type: application/json" \5  -d '{"version_id": "ver_xyz789"}'

Use PUT /apps/{id}/versions/{versionId}/current instead, with versionId in the path.