# App: Profiles

**Page:** api/app/profiles

[Download Raw Markdown](./api/app/profiles.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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.


When a profile is selected via `POST /api/v1/run/profiles/{profile}/select`, its defaults are merged into every subsequent request that does not explicitly override them. Deleting the currently selected profile clears the active selection.


## 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.



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


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


```json
[
  {
    "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`) |



```bash
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
    }
  }'
```


```ts
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 }
});
```


```json
[
  {
    "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 }
  }
]
```


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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 |



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


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


```json
{
  "selected_profile": "default"
}
```


```json
{
  "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 |


```json
{
  "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`.



```bash
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 }
  }'
```


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


```json
{
  "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
  }
}
```


```json
{
  "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 |


```json
{
  "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 |



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


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


The profile was deleted successfully. No content is returned.


```json
{
  "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 |


```json
{
  "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 |