App: Recipes

Manage and run application recipes — list, create, get, update, delete, search, and execute. Recipes are named selector templates that can be reused across multiple run or search operations with optional overrides.

List Saved Recipes

`GET /api/v1/run/recipes`

List all saved recipes that can be reused as named selector templates.

This endpoint takes no parameters.

cURL
SDK

curl -X GET 'http://127.0.0.1:7682/api/v1/run/recipes'

const recipes = await client.app.recipes.list();

Response: 200 — Recipe list

[
  {
    "name": "dev-shell",
    "description": "Default development environment",
    "selector_template": {
      "app": "node",
      "os": "linux",
      "kind": "cli",
      "version": "20"
    },
    "allowed_overrides": ["version", "channel"]
  },
  {
    "name": "browser",
    "description": "Default web browser",
    "selector_template": {
      "app": "firefox",
      "os": "linux",
      "kind": "gui"
    },
    "allowed_overrides": []
  }
]

Get a Saved Recipe

`GET /api/v1/run/recipes/{name}`

Retrieve a single saved recipe by name.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Recipe name

cURL
SDK

curl -X GET 'http://127.0.0.1:7682/api/v1/run/recipes/dev-shell'

const recipe = await client.app.recipes.get({ name: "dev-shell" });

Response: 200 — Recipe configuration

{
  "name": "dev-shell",
  "description": "Default development environment",
  "selector_template": {
    "app": "node",
    "os": "linux",
    "kind": "cli",
    "version": "20"
  },
  "allowed_overrides": ["version", "channel"]
}

Response: 404 — Recipe not found

{
  "error": "Recipe not found",
  "code": 404
}

Create a Saved Recipe

`POST /api/v1/run/recipes`

Create a named selector template that can later be searched or run with optional overrides.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Recipe name
`description`	string	No	Human-readable description
`selector_template`	object	No	Partial selector template used to resolve candidates
`allowed_overrides`	array	No	List of selector template fields that may be overridden at run time (default: `[]`)

{
  "name": "dev-shell",
  "description": "Default development environment",
  "selector_template": {
    "app": "node",
    "os": "linux",
    "kind": "cli",
    "version": "20"
  },
  "allowed_overrides": ["version", "channel"]
}

cURL
SDK

curl -X POST 'http://127.0.0.1:7682/api/v1/run/recipes' \
  -H 'content-type: application/json' \
  -d '{
    "name": "dev-shell",
    "description": "Default development environment",
    "selector_template": {
      "app": "node",
      "os": "linux",
      "kind": "cli",
      "version": "20"
    },
    "allowed_overrides": ["version", "channel"]
  }'

const recipes = await client.app.recipes.create({
  data: {
    name: "dev-shell",
    description: "Default development environment",
    selector_template: {
      app: "node",
      os: "linux",
      kind: "cli",
      version: "20"
    },
    allowed_overrides: ["version", "channel"]
  }
});

Response: 200 — Updated recipe list

[
  {
    "name": "dev-shell",
    "description": "Default development environment",
    "selector_template": {
      "app": "node",
      "os": "linux",
      "kind": "cli",
      "version": "20"
    },
    "allowed_overrides": ["version", "channel"]
  }
]

Response: 400 — Bad request

{
  "error": "Invalid recipe configuration",
  "code": 400
}

Response: 409 — Recipe already exists

{
  "error": "Recipe already exists",
  "code": 409
}

Run Using a Saved Recipe

`POST /api/v1/run/recipes/{name}/run`

Resolve and optionally select a candidate from a saved recipe after applying allowed overrides.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Recipe name

Request Body

Field	Type	Required	Description
`overrides`	object	No	Optional selector template overrides. Only fields listed in the recipe’s `allowed_overrides` are applied.

{
  "overrides": {
    "version": "22"
  }
}

cURL
SDK

curl -X POST 'http://127.0.0.1:7682/api/v1/run/recipes/dev-shell/run' \
  -H 'content-type: application/json' \
  -d '{
    "overrides": {
      "version": "22"
    }
  }'

const result = await client.app.recipes.run({
  name: "dev-shell",
  data: {
    overrides: {
      version: "22"
    }
  }
});

Response: 200 — Run result

{
  "status": "dry-run",
  "set_id": "a1b2c3d4e5f6",
  "selected": {
    "candidate_id": "nix-node-22",
    "title": "Node.js 22 (nixpkgs)",
    "description": "Node.js runtime via nixpkgs",
    "version": "22.0.0",
    "provider": "nix",
    "source_id": "nixpkgs",
    "score": 95,
    "run_plan": {
      "command": "nix run nixpkgs#nodejs"
    }
  },
  "shell_command": "nix run nixpkgs#nodejs"
}

Response: 400 — Bad request

{
  "error": "Override field 'version' is not in allowed_overrides",
  "code": 400
}

Response: 404 — Recipe not found

{
  "error": "Recipe not found",
  "code": 404
}

Response: 503 — Required local tools are unavailable

{
  "error": "Required local tools are unavailable",
  "code": 503
}

Search Using a Saved Recipe

`POST /api/v1/run/recipes/{name}/search`

Resolve a recipe to a candidate set after applying allowed overrides. Unlike the run endpoint, search does not select or execute a candidate — it returns the full ranked list for client-side selection.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Recipe name

Request Body

Field	Type	Required	Description
`overrides`	object	No	Optional selector template overrides. Only fields listed in the recipe’s `allowed_overrides` are applied.

{
  "overrides": {
    "version": "22"
  }
}

cURL
SDK

curl -X POST 'http://127.0.0.1:7682/api/v1/run/recipes/dev-shell/search' \
  -H 'content-type: application/json' \
  -d '{
    "overrides": {
      "version": "22"
    }
  }'

const result = await client.app.recipes.search({
  name: "dev-shell",
  data: {
    overrides: {
      version: "22"
    }
  }
});

Response: 200 — Search result

{
  "set_id": "a1b2c3d4e5f6",
  "candidates": [
    {
      "candidate_id": "nix-node-22",
      "title": "Node.js 22 (nixpkgs)",
      "description": "Node.js runtime via nixpkgs",
      "version": "22.0.0",
      "provider": "nix",
      "source_id": "nixpkgs",
      "score": 95,
      "reasons": ["exact version match", "high priority source"],
      "run_plan": {
        "command": "nix run nixpkgs#nodejs"
      }
    },
    {
      "candidate_id": "pkgx-node-22",
      "title": "Node.js 22 (pkgx)",
      "description": "Node.js runtime via pkgx",
      "version": "22.1.0",
      "provider": "pkgx",
      "source_id": "pkgx",
      "score": 80,
      "reasons": ["exact version match"],
      "run_plan": {
        "command": "pkgx +node@22 node"
      }
    }
  ]
}

Response: 400 — Bad request

{
  "error": "Override field 'version' is not in allowed_overrides",
  "code": 400
}

Response: 404 — Recipe not found

{
  "error": "Recipe not found",
  "code": 404
}

Update a Saved Recipe

`PATCH /api/v1/run/recipes/{name}`

Partially update an existing recipe.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Recipe name

Request Body

This endpoint accepts a partial recipe update. Any combination of recipe configuration fields may be supplied; only the provided fields are modified.

{
  "description": "Updated development environment",
  "allowed_overrides": ["version", "channel", "profile"]
}

cURL
SDK

curl -X PATCH 'http://127.0.0.1:7682/api/v1/run/recipes/dev-shell' \
  -H 'content-type: application/json' \
  -d '{
    "description": "Updated development environment",
    "allowed_overrides": ["version", "channel", "profile"]
  }'

const recipe = await client.app.recipes.update({
  name: "dev-shell",
  data: {
    description: "Updated development environment",
    allowed_overrides: ["version", "channel", "profile"]
  }
});

Response: 200 — Updated recipe configuration

{
  "name": "dev-shell",
  "description": "Updated development environment",
  "selector_template": {
    "app": "node",
    "os": "linux",
    "kind": "cli",
    "version": "20"
  },
  "allowed_overrides": ["version", "channel", "profile"]
}

Response: 404 — Recipe not found

{
  "error": "Recipe not found",
  "code": 404
}

Delete a Saved Recipe

`DELETE /api/v1/run/recipes/{name}`

Remove a saved recipe by name.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Recipe name

This endpoint takes no request body.

cURL
SDK

curl -X DELETE 'http://127.0.0.1:7682/api/v1/run/recipes/dev-shell'

await client.app.recipes.delete({ name: "dev-shell" });

Response: 204 — Recipe deleted successfully

No content.

Response: 404 — Recipe not found

{
  "error": "Recipe not found",
  "code": 404
}