Run: Recipes

Manage saved application recipes — reusable named selector templates that can be searched or run with optional overrides. Use these endpoints to create, inspect, update, and delete recipes, then resolve them into ranked candidate sets or execute them directly.

All requests are scoped to a container and addressed through the container-scoped run service host.

List recipes

`GET /api/v1/run/recipes`

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

This endpoint takes no parameters.

curl -sS -X GET \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes'

await client.run.recipes.listRecipes()

[
  {
    "name": "firefox",
    "description": "Launch Firefox from nixpkgs",
    "selector_template": {
      "app": "firefox",
      "os": "linux",
      "kind": "gui",
      "source": ["nix"],
      "arch": "amd64"
    },
    "allowed_overrides": ["arch", "channel"]
  },
  {
    "name": "ripgrep",
    "description": "Fast recursive grep alternative",
    "selector_template": {
      "app": "ripgrep",
      "os": "any",
      "kind": "cli",
      "source": ["nix", "pkgx"]
    },
    "allowed_overrides": []
  }
]

Get a 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 -sS -X GET \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes/firefox'

await client.run.recipes.getRecipe('firefox')

{
  "name": "firefox",
  "description": "Launch Firefox from nixpkgs",
  "selector_template": {
    "app": "firefox",
    "os": "linux",
    "kind": "gui",
    "source": ["nix"],
    "arch": "amd64"
  },
  "allowed_overrides": ["arch", "channel"]
}

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

Create a 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 of the recipe
`selector_template`	object	No	Partial selector template used to resolve candidates
`allowed_overrides`	array	No	List of selector fields the caller is permitted to override. Default: `[]`

curl -sS -X POST \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes' \
  -H 'content-type: application/json' \
  -d '{
    "name": "firefox",
    "description": "Launch Firefox from nixpkgs",
    "selector_template": {
      "app": "firefox",
      "os": "linux",
      "kind": "gui",
      "source": ["nix"],
      "arch": "amd64"
    },
    "allowed_overrides": ["arch", "channel"]
  }'

await client.run.recipes.createRecipe({
  name: 'firefox',
  description: 'Launch Firefox from nixpkgs',
  selector_template: {
    app: 'firefox',
    os: 'linux',
    kind: 'gui',
    source: ['nix'],
    arch: 'amd64',
  },
  allowed_overrides: ['arch', 'channel'],
})

[
  {
    "name": "firefox",
    "description": "Launch Firefox from nixpkgs",
    "selector_template": {
      "app": "firefox",
      "os": "linux",
      "kind": "gui",
      "source": ["nix"],
      "arch": "amd64"
    },
    "allowed_overrides": ["arch", "channel"]
  }
]

{
  "error": "invalid recipe payload",
  "code": 400
}

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

Update a 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 object.

curl -sS -X PATCH \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes/firefox' \
  -H 'content-type: application/json' \
  -d '{
    "description": "Launch Firefox from nixpkgs (stable channel)",
    "allowed_overrides": ["arch", "channel", "version"]
  }'

await client.run.recipes.updateRecipe('firefox', {
  description: 'Launch Firefox from nixpkgs (stable channel)',
  allowed_overrides: ['arch', 'channel', 'version'],
})

{
  "name": "firefox",
  "description": "Launch Firefox from nixpkgs (stable channel)",
  "selector_template": {
    "app": "firefox",
    "os": "linux",
    "kind": "gui",
    "source": ["nix"],
    "arch": "amd64"
  },
  "allowed_overrides": ["arch", "channel", "version"]
}

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

Delete a 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

curl -sS -X DELETE \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes/firefox'

await client.run.recipes.deleteRecipe('firefox')

Recipe deleted successfully

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

Run a 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	Partial selector template containing only the fields the recipe permits overriding. Values outside `allowed_overrides` are rejected.

curl -sS -X POST \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes/firefox/run' \
  -H 'content-type: application/json' \
  -d '{
    "overrides": {
      "channel": "unstable",
      "arch": "arm64",
      "pick": "first"
    }
  }'

await client.run.recipes.runRecipe('firefox', {
  overrides: {
    channel: 'unstable',
    arch: 'arm64',
    pick: 'first',
  },
})

{
  "status": "dry-run",
  "set_id": "a1b2c3d4e5f6",
  "selected": {
    "candidate_id": "nix-firefox-128",
    "title": "Firefox (nixpkgs)",
    "description": "Mozilla Firefox web browser via nixpkgs",
    "kind": "gui",
    "version": "128.0.3",
    "provider": "nix",
    "source_id": "nixpkgs",
    "score": 95,
    "run_plan": {
      "command": "nix run nixpkgs#firefox"
    }
  },
  "shell_command": "nix run nixpkgs#firefox",
  "warnings": []
}

{
  "error": "override not allowed",
  "code": 400
}

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

Search using a recipe

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

Resolve a recipe to a candidate set after applying allowed overrides, without selecting a single candidate. Use the returned set_id together with pick=id for race-free selection on a subsequent run.

Parameters

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

Request Body

Field	Type	Required	Description
`overrides`	object	No	Partial selector template containing only the fields the recipe permits overriding. Values outside `allowed_overrides` are rejected.

curl -sS -X POST \
  'https://abc123-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/recipes/firefox/search' \
  -H 'content-type: application/json' \
  -d '{
    "overrides": {
      "arch": "arm64"
    }
  }'

await client.run.recipes.searchRecipe('firefox', {
  overrides: { arch: 'arm64' },
})

{
  "set_id": "a1b2c3d4e5f6",
  "candidates": [
    {
      "candidate_id": "nix-firefox-128",
      "title": "Firefox (nixpkgs)",
      "description": "Mozilla Firefox web browser via nixpkgs",
      "kind": "gui",
      "version": "128.0.3",
      "provider": "nix",
      "source_id": "nixpkgs",
      "score": 95,
      "run_plan": {
        "command": "nix run nixpkgs#firefox"
      }
    },
    {
      "candidate_id": "pkgx-firefox-128",
      "title": "Firefox (pkgx)",
      "description": "Mozilla Firefox web browser via pkgx",
      "kind": "gui",
      "version": "128.0.1",
      "provider": "pkgx",
      "source_id": "pkgx-firefox",
      "score": 78,
      "run_plan": {
        "command": "pkgx firefox"
      }
    }
  ]
}

{
  "error": "override not allowed",
  "code": 400
}

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