App: Profiles

Download Page (.md)

The App Profiles API manages user profiles that bundle default selectors and source overrides. Use these endpoints to list, create, update, delete, and select the active profile that subsequent app-run requests will inherit from.

List profiles

`GET /api/v1/run/profiles`

List all configured user profiles with their default preferences and source overrides.

This endpoint takes no parameters.

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "defaults": {
      "os": "any",
      "kind": "any",
      "source": [],
      "pick": "ask",
      "redirect": false,
      "limit": 20
    },
    "sources_mode": "inherit",
    "sources": [],
    "policy": {
      "require_verified": true,
      "require_integrity": true,
      "allow_delegated_execution": false,
      "allow_redirect": true,
      "deny_providers": [],
      "deny_source_ids": []
    }
  },
  {
    "name": "trusted",
    "description": "Trusted providers only",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix", "pkgx"],
      "pick": "first",
      "limit": 10
    },
    "sources_mode": "allowlist",
    "sources": [
      { "source_id": "nixpkgs", "enabled": true, "priority": 100 },
      { "source_id": "pkgx", "enabled": true, "priority": 80 }
    ],
    "policy": {
      "require_verified": true,
      "require_integrity": true
    }
  }
]

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

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

Create a profile

`POST /api/v1/run/profiles`

Create a new user profile with default preferences and optional source overrides.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique profile name
`description`	string	No	Human-readable profile description
`defaults`	object	No	Default selector values applied to requests that do not explicitly set them
`sources_mode`	string	No	`inherit` to start from global sources, or `allowlist` to disable all sources except those listed in `sources`
`sources`	array	No	Per-source overrides. Default: `[]`
`policy`	object	No	Policy configuration controlling verification, integrity, execution, redirects, and provider denylists

[
  {
    "name": "minimal",
    "description": "Minimal profile for CLI tools",
    "defaults": {
      "kind": "cli",
      "pick": "first",
      "limit": 5
    },
    "sources_mode": "inherit",
    "sources": []
  }
]

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

curl -X POST "https://api.example.com/api/v1/run/profiles" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "minimal",
    "description": "Minimal profile for CLI tools",
    "defaults": {
      "kind": "cli",
      "pick": "first",
      "limit": 5
    }
  }'

const profiles = await client.app.profiles.create({
  name: "minimal",
  description: "Minimal profile for CLI tools",
  defaults: { kind: "cli", pick: "first", limit: 5 }
});

Select the active profile

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

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

Parameters

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

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

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

await client.app.profiles.select({ profile: "default" });

Update a profile

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

Partially update a profile configuration. Supports merging description, defaults, sources_mode, and sources fields.

Parameters

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

Request Body

The request body is a partial object. Any combination of description, defaults, sources_mode, and sources may be included. Only the fields present in the body are merged into the existing profile; omitted fields are left unchanged.

{
  "name": "default",
  "description": "Default profile (inherits global sources)",
  "defaults": {
    "os": "any",
    "kind": "any",
    "source": [],
    "pick": "ask",
    "redirect": false,
    "limit": 20
  },
  "sources_mode": "inherit",
  "sources": [
    { "source_id": "nixpkgs", "enabled": true, "priority": 100 }
  ],
  "policy": {
    "require_verified": true,
    "require_integrity": true,
    "allow_delegated_execution": false,
    "allow_redirect": true,
    "deny_providers": [],
    "deny_source_ids": []
  }
}

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

curl -X PATCH "https://api.example.com/api/v1/run/profiles/default" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Default profile (inherits global sources)",
    "sources": [
      { "source_id": "nixpkgs", "enabled": true, "priority": 100 }
    ]
  }'

const updated = await client.app.profiles.update({
  profile: "default",
  data: {
    description: "Default profile (inherits global sources)",
    sources: [{ source_id: "nixpkgs", enabled: true, priority: 100 }]
  }
});

Delete a profile

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

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

Parameters

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

The profile was deleted successfully. No response body is returned.

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

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

await client.app.profiles.delete({ profile: "old-profile" });