App: Execution

The App Execution API resolves applications from configured sources and either schedules them through hoody-terminal or returns the exact shell command to run. Use these endpoints to search candidates, preflight an execution plan, run individual apps (via query, path, or JSON body), or batch multiple operations in a single request.

Configuration

GET /api/v1/run/config

Returns the full persisted runtime configuration including sources, profiles, and the currently selected profile.

This endpoint takes no parameters.

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/config'

SDK

const config = await client.app.configuration.get();

Response 200

{
  "version": 3,
  "sources": [
    {
      "source_id": "nixpkgs",
      "enabled": true,
      "priority": 100,
      "provider": "nix",
      "source_type": "nix-flake",
      "config": {
        "flake": "nixpkgs"
      }
    }
  ],
  "profiles": [
    {
      "name": "default",
      "description": "Default profile (inherits global sources)",
      "defaults": {
        "os": "linux",
        "kind": "any",
        "pick": "first",
        "terminal_id": 1,
        "limit": 25
      },
      "sources_mode": "inherit"
    }
  ],
  "policy": {
    "require_verified": false,
    "allow_delegated_execution": true,
    "allow_redirect": true
  },
  "selected_profile": "default",
  "recipes": [],
  "webhooks": []
}

---

API Documentation

GET /api/v1/run/openapi.json

Returns the OpenAPI 3.0.3 specification for this API in JSON format. Converted from the canonical YAML source.

This endpoint takes no parameters.

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/openapi.json'

SDK

const spec = await client.app.docs.getJson();

Response 200

{
  "openapi": "3.0.3",
  "info": {
    "title": "hoody-run",
    "version": "1.0.0"
  },
  "paths": {}
}

GET /api/v1/run/openapi.yaml

Returns the OpenAPI 3.0.3 specification for this API in YAML format.

This endpoint takes no parameters.

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/openapi.yaml'

SDK

const spec = await client.app.docs.getYaml();

Response 200

openapi: 3.0.3
info:
  title: hoody-run
  version: 1.0.0
paths: {}

---

Search

GET /api/v1/run/search

Search for runnable application candidates across all configured and enabled package sources. Returns a ranked list of candidates with stable ordering for pick-by-index operations. The returned set_id can be used with subsequent run requests to ensure race-free candidate selection.

Parameters

Name	In	Type	Required	Description
app	query	string	Yes	Primary name query (aliases q, name)
os	query	string (linux, windows, any)	No	Target OS filter
source	query	array	No	Source kind filter (repeatable)
kind	query	string (gui, cli, any)	No	App kind filter
arch	query	string (amd64, arm64, any)	No	Target CPU architecture filter
tags	query	array	No	Free-form tags for filtering and ranking (repeatable)
profile	query	string	No	Named profile for default preferences
channel	query	string	No	Release channel hint (for example stable or beta)
version	query	string	No	Exact version or provider-defined version constraint
variant	query	string	No	Provider-specific variant hint (for example portable or headless)
publisher	query	string	No	Publisher hint for curated registries
repo	query	string	No	Repository hint such as owner/name
release	query	string	No	Release hint such as a tag name
asset	query	string	No	Desired asset name or pattern
limit	query	integer	No	Max candidates to return (default 25)

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/search?app=firefox&os=linux&limit=10'

SDK

const result = await client.app.execution.searchCandidates({
  app: "firefox",
  os: "linux",
  limit: 10
});

Response 200

{
  "set_id": "a1b2c3d4e5f6",
  "candidates": [
    {
      "candidate_id": "nix-firefox-128",
      "title": "Firefox (nixpkgs)",
      "description": "Mozilla Firefox web browser via nixpkgs",
      "version": "128.0.3",
      "homepage": "https://www.mozilla.org/firefox/",
      "tags": ["browser", "web"],
      "provider": "nix",
      "source_id": "nixpkgs",
      "score": 95,
      "reasons": ["exact name match", "high priority source"],
      "run_plan": {
        "command": "nix run nixpkgs#firefox",
        "env": {
          "MOZ_ENABLE_WAYLAND": "0"
        }
      },
      "verified": true,
      "shell_command": "nix run nixpkgs#firefox",
      "href_path": "/api/v1/run/run?app=firefox&os=linux&kind=any&pick=id&candidate_id=nix-firefox-128&set_id=a1b2c3d4e5f6"
    }
  ]
}

Response 400

{
  "error": "missing app",
  "code": 400
}

Error Code	Title	Description	Resolution
MISSING_APP	Missing app query	No app name was provided in the request	Set app, q, or name to the desired program
INVALID_SELECTOR	Invalid selector parameter	One or more selector parameters could not be parsed	Check enum values and numeric fields, then retry
UNKNOWN_PROFILE	Unknown profile	The requested profile does not exist	Call listProfiles or getConfig and choose a valid profile name

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

Error Code	Title	Description	Resolution
SOURCE_RESOLUTION_FAILED	Source resolution failed	Candidate resolution could not be completed because upstream source work failed	Retry or inspect provider/source health

POST /api/v1/run/search/paged

Resolve a full ranked candidate set under a bounded cap, then page through it with an opaque cursor. This is the stable pagination contract for large result sets.

This endpoint takes no parameters.

Request Body

Accepts a JSON body matching the PagedSearchRequest schema.

{
  "selector": {
    "app": "firefox",
    "os": "linux",
    "kind": "any",
    "limit": 100
  },
  "cursor": null,
  "page_size": 25
}

cURL

curl -sS -X POST 'http://127.0.0.1:7682/api/v1/run/search/paged' \
  -H 'content-type: application/json' \
  -d '{"selector":{"app":"firefox","os":"linux","limit":100},"page_size":25}'

SDK

const iterator = client.app.execution.searchCandidatesPagedIterator({
  selector: { app: "firefox", os: "linux", limit: 100 },
  page_size: 25
});

for await (const page of iterator) {
  // process candidates
}

Response 200

{
  "set_id": "a1b2c3d4e5f6",
  "total_count": 42,
  "items": [
    {
      "candidate_id": "nix-firefox-128",
      "title": "Firefox (nixpkgs)",
      "description": "Mozilla Firefox web browser via nixpkgs",
      "version": "128.0.3",
      "provider": "nix",
      "source_id": "nixpkgs",
      "score": 95,
      "run_plan": {
        "command": "nix run nixpkgs#firefox"
      }
    }
  ],
  "next_cursor": "eyJwYWdlIjoyfQ=="
}

Response 400

{
  "error": "invalid selector",
  "code": 400
}

Response 409

{
  "error": "cursor set expired",
  "code": 409
}

Error Code	Title	Description	Resolution
CURSOR_SET_EXPIRED	Cursor set expired	The cached candidate set referenced by the cursor is no longer available	Restart pagination from the first page

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

---

Preflight

POST /api/v1/run/preflight

Resolve, optionally pick, and normalize the execution plan for a selector without scheduling execution.

This endpoint takes no parameters.

Request Body

Accepts a JSON body matching the Selector schema.

{
  "app": "firefox",
  "os": "linux",
  "kind": "any",
  "pick": "first",
  "terminal_id": 1
}

cURL

curl -sS -X POST 'http://127.0.0.1:7682/api/v1/run/preflight' \
  -H 'content-type: application/json' \
  -d '{"app":"firefox","os":"linux","kind":"any","pick":"first","terminal_id":1}'

SDK

const result = await client.app.execution.preflight({
  app: "firefox",
  os: "linux",
  kind: "any",
  pick: "first",
  terminal_id: 1
});

Response 200

{
  "set_id": "a1b2c3d4e5f6",
  "selected": {
    "candidate_id": "nix-firefox-128",
    "title": "Firefox (nixpkgs)",
    "description": "Mozilla Firefox web browser via nixpkgs",
    "version": "128.0.3",
    "provider": "nix",
    "source_id": "nixpkgs",
    "score": 95,
    "run_plan": {
      "command": "nix run nixpkgs#firefox",
      "env": {
        "MOZ_ENABLE_WAYLAND": "0"
      }
    }
  },
  "shell_command": "nix run nixpkgs#firefox",
  "recommended_mode": "dry-run",
  "terminal_request_preview": {
    "terminal_url": "http://127.0.0.1:7681/api/v1/terminal/execute",
    "terminal_id": 1,
    "display": ":1",
    "origin": "hoody-run",
    "command": "nix run nixpkgs#firefox"
  },
  "redirect_target": "/api/v1/run/run?app=firefox&set_id=a1b2c3d4e5f6",
  "missing_requirements": [],
  "warnings": [],
  "effective_policy": {
    "require_verified": false,
    "require_integrity": false,
    "allow_delegated_execution": true,
    "allow_redirect": true,
    "deny_providers": [],
    "deny_source_ids": []
  }
}

Response 400

{
  "error": "invalid selector",
  "code": 400
}

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

---

App Execution

GET /api/v1/run/run

Resolve and select an application using query parameters, then return the exact shell command to run. By default this endpoint is command-only and does not call hoody-terminal. Legacy delegation is opt-in via HOODY_RUN_ENABLE_TERMINAL_EXECUTE=true. Supports all selector fields plus pick mode, output control, deferred execution metadata, and redirect behavior.

Parameters

Name	In	Type	Required	Description
app	query	string	Yes	Primary name query
os	query	string (linux, windows, any)	No	Target OS filter
source	query	array	No	Source kind filter (repeatable)
kind	query	string (gui, cli, any)	No	App kind filter
arch	query	string (amd64, arm64, any)	No	Target CPU architecture filter
tags	query	array	No	Free-form tags for filtering and ranking (repeatable)
profile	query	string	No	Named profile for default preferences
channel	query	string	No	Release channel hint
version	query	string	No	Exact version or provider-defined version constraint
variant	query	string	No	Provider-specific variant hint
publisher	query	string	No	Publisher hint for curated registries
repo	query	string	No	Repository hint such as owner/name
release	query	string	No	Release hint such as a tag name
asset	query	string	No	Desired asset name or pattern
pick	query	string (ask, first, index, id)	No	Candidate selection mode
pick_index	query	integer	No	Candidate index (required when pick=index)
candidate_id	query	string	No	Specific candidate ID (required when pick=id)
set_id	query	string	No	Bind pick to a specific candidate set
terminal_id	query	integer	No	Terminal session ID (default 1)
display	query	string	No	X11 DISPLAY number
origin	query	string	No	Origin identifier for observability propagation
defer_pid	query	integer	No	Defer command injection until this PID exits
defer_start_time_ticks	query	string	No	Start-time ticks used to avoid PID reuse bugs
defer_timeout_ms	query	integer	No	Maximum defer wait time in milliseconds
defer_poll_ms	query	integer	No	Defer polling interval in milliseconds
dry_run	query	boolean	No	If true, force command-only response (no delegation)
print_curl	query	string (hoody-run, hoody-terminal)	No	Generate curl command
format	query	string (json, html)	No	Output format
redirect	query	boolean	No	Redirect to display page after scheduling
redirect_to	query	string	No	Override redirect target URL
limit	query	integer	No	Max candidates (default 25)

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/run?app=firefox&os=linux&pick=first'

SDK

const result = await client.app.execution.runAppGet({
  app: "firefox",
  os: "linux",
  pick: "first"
});

Response 200

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

Response 400

{
  "error": "missing app",
  "code": 400
}

Error Code	Title	Description	Resolution
MISSING_APP	Missing app query	No app name was provided in the request	Set app to the desired program name
INVALID_SELECTOR	Invalid selector parameter	One or more selector parameters could not be parsed	Check enum values and numeric fields, then retry
UNKNOWN_PROFILE	Unknown profile	The requested profile does not exist	Choose a profile returned by listProfiles or getConfig
INVALID_PICK	Invalid pick request	The pick mode requirements were not satisfied or the selected candidate was not found	Search first, then supply a valid pick_index or candidate_id

Response 500

{
  "error": "invalid terminal URL",
  "code": 500
}

Error Code	Title	Description	Resolution
INVALID_TERMINAL_URL	Invalid terminal URL	Curl generation could not build a valid hoody-terminal execute URL	Check HOODY_TERMINAL_URL and retry

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

Error Code	Title	Description	Resolution
SOURCE_RESOLUTION_FAILED	Source resolution failed	Candidate resolution could not be completed because upstream source work failed	Retry or inspect provider/source health

Response 503

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

Error Code	Title	Description	Resolution
LOCAL_TOOLS_UNAVAILABLE	Required local tools are unavailable	The selected candidate requires local tooling that is not currently available	Install or repair the required toolchain, then retry

POST /api/v1/run/run

Same behavior as GET /api/v1/run/run but accepts the full Selector as a JSON request body. Useful for programmatic clients and complex selectors.

This endpoint takes no parameters.

Request Body

Accepts a JSON body matching the Selector schema.

{
  "app": "firefox",
  "os": "linux",
  "kind": "any",
  "source": ["nix"],
  "pick": "first",
  "terminal_id": 1,
  "format": "json"
}

cURL

curl -sS -X POST 'http://127.0.0.1:7682/api/v1/run/run' \
  -H 'content-type: application/json' \
  -d '{"app":"firefox","os":"linux","kind":"any","pick":"first","terminal_id":1}'

SDK

const result = await client.app.execution.runAppPost({
  app: "firefox",
  os: "linux",
  kind: "any",
  pick: "first",
  terminal_id: 1
});

Response 200

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

Response 400

{
  "error": "missing app",
  "code": 400
}

Error Code	Title	Description	Resolution
MISSING_APP	Missing app query	No app name was provided in the request body	Set app to the desired program name
INVALID_SELECTOR	Invalid selector parameter	One or more selector fields could not be parsed	Check enum values and numeric fields, then retry
UNKNOWN_PROFILE	Unknown profile	The requested profile does not exist	Choose a profile returned by listProfiles or getConfig
INVALID_PICK	Invalid pick request	The pick mode requirements were not satisfied or the selected candidate was not found	Search first, then supply a valid pick_index or candidate_id

Response 500

{
  "error": "invalid terminal URL",
  "code": 500
}

Error Code	Title	Description	Resolution
INVALID_TERMINAL_URL	Invalid terminal URL	Curl generation could not build a valid hoody-terminal execute URL	Check HOODY_TERMINAL_URL and retry

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

Error Code	Title	Description	Resolution
SOURCE_RESOLUTION_FAILED	Source resolution failed	Candidate resolution could not be completed because upstream source work failed	Retry or inspect provider/source health

Response 503

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

Error Code	Title	Description	Resolution
LOCAL_TOOLS_UNAVAILABLE	Required local tools are unavailable	The selected candidate requires local tooling that is not currently available	Install or repair the required toolchain, then retry

GET /api/v1/run/go/{rest}

Resolve an application using clean, bookmarkable path-based URLs. Supports both positional and key-value path segments.

Positional: /api/v1/run/go/{app}, /api/v1/run/go/{os}/{app}, /api/v1/run/go/{os}/{source}/{app}, /api/v1/run/go/{os}/{source}/{kind}/{app}

Key-value: /api/v1/run/go/app/{app}/os/{os}/source/{source}/kind/{kind}/pick/{pick}/...

Parameters

Name	In	Type	Required	Description
rest	path	string	Yes	Path segments for positional or key-value app specification
os	query	string (linux, windows, any)	No	Target OS filter when not supplied in the path
source	query	array	No	Source kind filter (repeatable)
kind	query	string (gui, cli, any)	No	App kind filter when not supplied in the path
arch	query	string (amd64, arm64, any)	No	Target CPU architecture filter
tags	query	array	No	Free-form tags for filtering and ranking (repeatable)
profile	query	string	No	Named profile for default preferences
channel	query	string	No	Release channel hint
version	query	string	No	Exact version or provider-defined version constraint
variant	query	string	No	Provider-specific variant hint
publisher	query	string	No	Publisher hint for curated registries
repo	query	string	No	Repository hint such as owner/name
release	query	string	No	Release hint such as a tag name
asset	query	string	No	Desired asset name or pattern
pick	query	string (ask, first, index, id)	No	Candidate selection mode
pick_index	query	integer	No	Candidate index (required when pick=index)
candidate_id	query	string	No	Specific candidate ID (required when pick=id)
set_id	query	string	No	Bind pick to a specific candidate set
terminal_id	query	integer	No	Terminal session ID when not supplied in the path
display	query	string	No	X11 DISPLAY number
origin	query	string	No	Origin identifier for observability propagation
defer_pid	query	integer	No	Defer command injection until this PID exits
defer_start_time_ticks	query	string	No	Start-time ticks used to avoid PID reuse bugs
defer_timeout_ms	query	integer	No	Maximum defer wait time in milliseconds
defer_poll_ms	query	integer	No	Defer polling interval in milliseconds
dry_run	query	boolean	No	If true, force command-only response (no delegation)
print_curl	query	string (hoody-run, hoody-terminal)	No	Generate curl command
format	query	string (json, html)	No	Output format
redirect	query	boolean	No	Redirect to display page after scheduling
redirect_to	query	string	No	Override redirect target URL
limit	query	integer	No	Max candidates (default 25)

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/go/linux/nix/firefox?pick=first'

SDK

const result = await client.app.execution.runPathBased({
  rest: "linux/nix/firefox",
  pick: "first"
});

Response 200

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

Response 400

{
  "error": "missing app",
  "code": 400
}

Error Code	Title	Description	Resolution
MISSING_APP	Missing app query	No app name was provided in the request	Set the app in the path or query string
INVALID_SELECTOR	Invalid selector parameter	One or more selector parameters could not be parsed	Check enum values and numeric fields, then retry
UNKNOWN_PROFILE	Unknown profile	The requested profile does not exist	Choose a profile returned by listProfiles or getConfig
INVALID_PICK	Invalid pick request	The pick mode requirements were not satisfied or the selected candidate was not found	Search first, then supply a valid pick_index or candidate_id

Response 500

{
  "error": "invalid terminal URL",
  "code": 500
}

Error Code	Title	Description	Resolution
INVALID_TERMINAL_URL	Invalid terminal URL	Curl generation could not build a valid hoody-terminal execute URL	Check HOODY_TERMINAL_URL and retry

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

Error Code	Title	Description	Resolution
SOURCE_RESOLUTION_FAILED	Source resolution failed	Candidate resolution could not be completed because upstream source work failed	Retry or inspect provider/source health

Response 503

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

Error Code	Title	Description	Resolution
LOCAL_TOOLS_UNAVAILABLE	Required local tools are unavailable	The selected candidate requires local tooling that is not currently available	Install or repair the required toolchain, then retry

GET /api/v1/run/t/{terminal_id}/go/{rest}

Same as /api/v1/run/go/{rest} but with terminal_id extracted from the path prefix. Allows clean URLs that specify both the target terminal and the application in a single path.

Example: /api/v1/run/t/2/go/linux/nix/firefox runs Firefox in terminal 2.

Parameters

Name	In	Type	Required	Description
terminal_id	path	integer	Yes	Terminal session ID (1-65535)
rest	path	string	Yes	Path segments for app specification
os	query	string (linux, windows, any)	No	Target OS filter when not supplied in the path
source	query	array	No	Source kind filter (repeatable)
kind	query	string (gui, cli, any)	No	App kind filter when not supplied in the path
arch	query	string (amd64, arm64, any)	No	Target CPU architecture filter
tags	query	array	No	Free-form tags for filtering and ranking (repeatable)
profile	query	string	No	Named profile for default preferences
channel	query	string	No	Release channel hint
version	query	string	No	Exact version or provider-defined version constraint
variant	query	string	No	Provider-specific variant hint
publisher	query	string	No	Publisher hint for curated registries
repo	query	string	No	Repository hint such as owner/name
release	query	string	No	Release hint such as a tag name
asset	query	string	No	Desired asset name or pattern
pick	query	string (ask, first, index, id)	No	Candidate selection mode
pick_index	query	integer	No	Candidate index (required when pick=index)
candidate_id	query	string	No	Specific candidate ID (required when pick=id)
set_id	query	string	No	Bind pick to a specific candidate set
display	query	string	No	X11 DISPLAY number
origin	query	string	No	Origin identifier for observability propagation
defer_pid	query	integer	No	Defer command injection until this PID exits
defer_start_time_ticks	query	string	No	Start-time ticks used to avoid PID reuse bugs
defer_timeout_ms	query	integer	No	Maximum defer wait time in milliseconds
defer_poll_ms	query	integer	No	Defer polling interval in milliseconds
dry_run	query	boolean	No	If true, force command-only response (no delegation)
print_curl	query	string (hoody-run, hoody-terminal)	No	Generate curl command
format	query	string (json, html)	No	Output format
redirect	query	boolean	No	Redirect to display page after scheduling
redirect_to	query	string	No	Override redirect target URL
limit	query	integer	No	Max candidates (default 25)

cURL

curl -sS 'http://127.0.0.1:7682/api/v1/run/t/2/go/linux/nix/firefox?pick=first'

SDK

const result = await client.app.execution.runTerminalAnchored({
  terminal_id: 2,
  rest: "linux/nix/firefox",
  pick: "first"
});

Response 200

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

Response 400

{
  "error": "missing app",
  "code": 400
}

Error Code	Title	Description	Resolution
MISSING_APP	Missing app query	No app name was provided in the request	Set the app in the path or query string
INVALID_SELECTOR	Invalid selector parameter	One or more selector parameters could not be parsed	Check enum values and numeric fields, then retry
UNKNOWN_PROFILE	Unknown profile	The requested profile does not exist	Choose a profile returned by listProfiles or getConfig
INVALID_PICK	Invalid pick request	The pick mode requirements were not satisfied or the selected candidate was not found	Search first, then supply a valid pick_index or candidate_id

Response 500

{
  "error": "invalid terminal URL",
  "code": 500
}

Error Code	Title	Description	Resolution
INVALID_TERMINAL_URL	Invalid terminal URL	Curl generation could not build a valid hoody-terminal execute URL	Check HOODY_TERMINAL_URL and retry

Response 502

{
  "error": "source resolution failed",
  "code": 502
}

Error Code	Title	Description	Resolution
SOURCE_RESOLUTION_FAILED	Source resolution failed	Candidate resolution could not be completed because upstream source work failed	Retry or inspect provider/source health

Response 503

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

Error Code	Title	Description	Resolution
LOCAL_TOOLS_UNAVAILABLE	Required local tools are unavailable	The selected candidate requires local tooling that is not currently available	Install or repair the required toolchain, then retry

POST /api/v1/run/batch

Process multiple search or command-only run items in one request. Each item produces its own success or error payload.

This endpoint takes no parameters.

Request Body

Accepts a JSON body matching the BatchRequest schema.

{
  "items": [
    {
      "request_id": "req-1",
      "mode": "search",
      "selector": {
        "app": "firefox",
        "os": "linux",
        "limit": 5
      }
    },
    {
      "request_id": "req-2",
      "mode": "run",
      "selector": {
        "app": "firefox",
        "pick": "first",
        "terminal_id": 1
      }
    }
  ]
}

cURL

curl -sS -X POST 'http://127.0.0.1:7682/api/v1/run/batch' \
  -H 'content-type: application/json' \
  -d '{"items":[{"request_id":"req-1","mode":"search","selector":{"app":"firefox","os":"linux","limit":5}},{"request_id":"req-2","mode":"run","selector":{"app":"firefox","pick":"first","terminal_id":1}}]}'

SDK

const result = await client.app.execution.runBatch({
  items: [
    {
      request_id: "req-1",
      mode: "search",
      selector: { app: "firefox", os: "linux", limit: 5 }
    },
    {
      request_id: "req-2",
      mode: "run",
      selector: { app: "firefox", pick: "first", terminal_id: 1 }
    }
  ]
});

Response 200

{
  "items": [
    {
      "result": "search",
      "request_id": "req-1",
      "search": {
        "set_id": "a1b2c3d4e5f6",
        "candidates": [
          {
            "candidate_id": "nix-firefox-128",
            "title": "Firefox (nixpkgs)",
            "description": "Mozilla Firefox web browser via nixpkgs",
            "version": "128.0.3",
            "provider": "nix",
            "source_id": "nixpkgs",
            "score": 95,
            "run_plan": {
              "command": "nix run nixpkgs#firefox"
            }
          }
        ]
      }
    },
    {
      "result": "run",
      "request_id": "req-2",
      "run": {
        "status": "dry-run",
        "set_id": "a1b2c3d4e5f6",
        "shell_command": "nix run nixpkgs#firefox"
      }
    }
  ]
}