# Config, Endpoints, Keys, Profiles, And Projects

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/config` | Get daemon config and settings |
| `PATCH` | `/v1/config` | Update settings |
| `GET` | `/v1/config/model` | Show active model |
| `PUT` | `/v1/config/model` | Switch model |
| `POST` | `/v1/config/model/check` | Probe model readiness with non-empty text |
| `GET` | `/v1/config/endpoint` | Show active backend endpoint |
| `PUT` | `/v1/config/endpoint` | Switch endpoint with TUI-compatible normalization |
| `POST` | `/v1/config/endpoint/test` | Probe endpoint from daemon process |
| `GET` | `/v1/config/endpoint/history` | List recently used endpoints |
| `DELETE` | `/v1/config/endpoint/history` | Remove an endpoint from history |
| `POST` | `/v1/share/generate` | Generate a remote-access share URL |
| `GET` | `/v1/keys` | List runtime API keys |
| `POST` | `/v1/keys` | Mint runtime API key |
| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |
| `GET` | `/v1/profiles` | List tool profiles |
| `POST` | `/v1/profiles` | Create a tool profile |
| `GET` | `/v1/profiles/{name}` | Get profile details |
| `DELETE` | `/v1/profiles/{name}` | Delete profile |
| `GET` | `/v1/projects` | List known projects |
| `GET` | `/v1/projects/current` | Get active project |
| `POST` | `/v1/projects/switch` | Switch active project |
| `POST` | `/v1/projects/register` | Register project root |
| `POST` | `/v1/projects/rename` | Rename project |
| `GET` | `/v1/projects/scan` | Scan configured roots for project workspaces |
| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read, patch, or reset project preferences |
| `GET` | `/v1/admin/access` | Read daemon network access mode |
| `POST` | `/v1/admin/access` | Persist a new access mode from loopback only |

## Endpoint Switching

Endpoint switching uses the same normalization as the TUI. Use `/v1/config/endpoint/test` before switching a remote endpoint in automation.

Endpoint history mirrors the `/endpoint` TUI flow. It records recently used endpoints with metadata so users can reselect external routers, sponsor endpoints, and OpenAI-compatible URLs without retyping them.

`POST /v1/share/generate` creates a remote-access URL embedding the daemon host and auth material needed by the browser client. Use it only in authenticated contexts.

## Model Switching

`PUT /v1/config/model` updates the active model for subsequent requests and the daemon process, so `GET /v1/config/model` is read-after-write consistent. Clients can still pass per-request `model` fields to chat endpoints.

`POST /v1/config/model/check` performs a bounded real generation and returns
`ok`, `backend_normalized_model_id`, `provider_model_id`, endpoint metadata,
and whether non-empty visible text was produced. Use it to distinguish model
catalog visibility from compute readiness. The default is a 10-second, 8-token
probe; `timeout_ms` is capped at 30 seconds and `max_tokens` at 32, independent
of the general backend timeout. A real timeout is returned as typed HTTP 504
`model_check_timeout`; empty or malformed generation responses do not count as
ready.

## Runtime Keys

Runtime keys are persistent, scoped, and revocable. See `docs/rest/auth-and-scopes.md`.

## Profiles

Profiles constrain tools and runtime behavior for a key or request path. Use them for CI, dashboards, or remote clients that should not receive the full local tool surface.

## Projects

The daemon is process-wide, but project endpoints track the active workspace and per-project preferences such as selected model, chat session, and UI choices.

The dashboard brand picker uses `/v1/projects` and `/v1/projects/switch`.
`/v1/projects/scan` discovers candidate roots without activating them. Access
mode mutation is loopback-only even if the daemon currently permits any address.