App: Profiles

Download Page (.md)

User profiles bundle a set of default selectors, source overrides, and policy constraints that get applied to subsequent app requests. Use the endpoints on this page to list existing profiles, create new ones, update their configuration, select the active profile, or delete profiles that are no longer needed.

List profiles

Returns every configured user profile with its default preferences and source overrides. Use this to discover available profiles before selecting one or composing a new configuration.

`GET /api/v1/run/profiles`

This endpoint takes no parameters.

curl https://api.hoody.com/api/v1/run/profiles \
  -H "Authorization: Bearer <token>"

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

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "defaults": {
      "os": "linux",
      "kind": "any",
      "source": ["nix", "pkgx"],
      "pick": "ask",
      "limit": 20
    },
    "sources_mode": "inherit",
    "sources": [],
    "policy": {
      "require_verified": true,
      "allow_redirect": true
    }
  }
]

Create profile

Creates a new user profile with default preferences and optional source overrides. The name field is required and must be unique. Returns the updated list of all profiles on success.

`POST /api/v1/run/profiles`

This endpoint takes no parameters.

Request Body

Send a ProfileConfig object describing the new profile.

Name	Type	Required	Description
`name`	string	Yes	Unique profile name
`description`	string	No	Human-readable profile description
`defaults`	object	No	Default selector values applied when the profile is active (see `ProfileDefaults`)
`sources_mode`	string	No	`inherit` starts from global sources, `allowlist` disables all sources first
`sources`	array	No	Per-source overrides (enable/disable/reprioritize). Default: `[]`
`policy`	object	No	Policy constraints for the profile (see `PolicyConfig`)

curl -X POST https://api.hoody.com/api/v1/run/profiles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workstation",
    "description": "Linux GUI workstation",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix", "appimage"],
      "pick": "first"
    },
    "sources_mode": "allowlist",
    "policy": {
      "require_verified": true,
      "allow_redirect": true
    }
  }'

await client.app.profiles.create({
  name: "workstation",
  description: "Linux GUI workstation",
  defaults: { os: "linux", kind: "gui", source: ["nix", "appimage"], pick: "first" },
  sources_mode: "allowlist",
  policy: { require_verified: true, allow_redirect: true }
});

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "defaults": { "os": "linux", "kind": "any", "pick": "ask" },
    "sources_mode": "inherit",
    "sources": [],
    "policy": { "require_verified": true, "allow_redirect": true }
  },
  {
    "name": "workstation",
    "description": "Linux GUI workstation",
    "defaults": { "os": "linux", "kind": "gui", "source": ["nix", "appimage"], "pick": "first" },
    "sources_mode": "allowlist",
    "sources": [],
    "policy": { "require_verified": true, "allow_redirect": true }
  }
]

{
  "error": "missing profile name",
  "code": 400
}

Error Code	Title	Description	Resolution
`MISSING_PROFILE_NAME`	Missing profile name	The profile configuration did not include a non-empty name	Set `name` before creating the profile

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

Error Code	Title	Description	Resolution
`PROFILE_ALREADY_EXISTS`	Profile already exists	A profile with the same name already exists	Choose a unique profile name or update the existing profile instead

{
  "error": "configuration save failed",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile configuration could not be persisted	Check storage health and retry

Select active profile

Sets the named profile as the currently active profile. Its defaults will be applied to all subsequent requests that do not explicitly override them.

`POST /api/v1/run/profiles/{profile}/select`

Parameters

Name	In	Type	Required	Description
`profile`	path	string	Yes	Profile name to select

curl -X POST https://api.hoody.com/api/v1/run/profiles/default/select \
  -H "Authorization: Bearer <token>"

await client.app.profiles.select("default");

{
  "selected_profile": "default"
}

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

Error Code	Title	Description	Resolution
`PROFILE_NOT_FOUND`	Profile not found	No profile exists with the requested name	Call `list` and choose a valid profile name

{
  "error": "configuration save failed",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile selection could not be persisted	Check storage health and retry

Update profile

Partially updates a profile configuration. Only the fields included in the request body are modified; omitted fields retain their current values.

`PATCH /api/v1/run/profiles/{profile}`

Parameters

Name	In	Type	Required	Description
`profile`	path	string	Yes	Profile name

Request Body

Send a JSON object containing the subset of ProfileConfig fields to update. The supported merge fields are description, defaults, sources_mode, and sources.

curl -X PATCH https://api.hoody.com/api/v1/run/profiles/workstation \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Linux GUI workstation (revised)",
    "defaults": { "limit": 30 }
  }'

await client.app.profiles.update("workstation", {
  description: "Linux GUI workstation (revised)",
  defaults: { limit: 30 }
});

{
  "name": "workstation",
  "description": "Linux GUI workstation (revised)",
  "defaults": {
    "os": "linux",
    "kind": "gui",
    "source": ["nix", "appimage"],
    "pick": "first",
    "limit": 30
  },
  "sources_mode": "allowlist",
  "sources": [],
  "policy": {
    "require_verified": true,
    "allow_redirect": true
  }
}

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

Error Code	Title	Description	Resolution
`PROFILE_NOT_FOUND`	Profile not found	No profile exists with the requested name	Call `list` and choose a valid profile name

{
  "error": "configuration save failed",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile configuration could not be persisted	Check storage health and retry

Delete profile

Removes a profile by name. If the deleted profile was the selected profile, the active selection is cleared.

`DELETE /api/v1/run/profiles/{profile}`

Parameters

Name	In	Type	Required	Description
`profile`	path	string	Yes	Profile name

curl -X DELETE https://api.hoody.com/api/v1/run/profiles/workstation \
  -H "Authorization: Bearer <token>"

await client.app.profiles.delete("workstation");

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

Error Code	Title	Description	Resolution
`PROFILE_NOT_FOUND`	Profile not found	No profile exists with the requested name	Call `list` and choose a valid profile name

{
  "error": "configuration save failed",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile configuration could not be persisted	Check storage health and retry