# HTTP quickstart

> **Upcoming in 1.0 (preview). These pages describe the main branch of LLMSlim Core, which becomes the 0.13 release candidate and then 1.0. `pip install llmslim` installs 0.12.0 today, which doesn't have everything described here.** Docs for what pip installs: https://www.llmslim.app/docs.md

> llmslim serve: the same memory behind a small JSON API, for apps in any language.

Run llmslim serve, store and search memory with curl, add API keys, and run the server from Python.

Category: Getting Started · Version: 1.0 · Updated: November 2026 · 5 min read

## Install and run

One process and one SQLite file. Without a key it binds only the loopback interface, and needs no key there.

terminal:

```bash
pip install "llmslim[server]"
llmslim serve          # http://127.0.0.1:8080
```

## Store and search

Messages are stored word for word. A search returns all of a scope's history when it fits the budget, and otherwise the turns that answer the query.

terminal:

```bash
curl -s localhost:8080/v1/memories -H 'content-type: application/json' \
  -d '{"user_id": "asha", "messages": [{"role": "user", "content": "I moved to Pune last month."}]}'

curl -s localhost:8080/v1/memories/search -H 'content-type: application/json' \
  -d '{"user_id": "asha", "query": "Where did I move to?", "budget": 1500}'
```

search response (shortened):

```json
{"query":"Where did I move to?","text":"[2026-11-02 (Mon) 04:04] user: I moved to Pune last month.","tokens":24,"budget":1500,"history_tokens":24,"sessions_total":1,"sessions_kept":1,"elapsed_ms":101.81,"turns":[{"id":"83eb3732...","role":"user","content":"I moved to Pune last month.","score":0.236,"partial":false,...}],"requests":[],"preferences":[],"conflicts":[]}
```

Put `text` into your prompt as data, not instructions, in the new user turn (see [the Python quickstart](https://www.llmslim.app/docs/1.0/quickstart-python#prompt)).

## Serve other machines

To serve a network, set one or more keys; clients then send `Authorization: Bearer <key>` on every `/v1` request. Keys are compared in constant time and must be at least 16 characters; `--new-key` prints a random 43-character one.

terminal:

```bash
export LLMSLIM_API_KEYS="$(llmslim serve --new-key)"
llmslim serve --host 0.0.0.0 --port 8080 --db /var/lib/llmslim/memory.db
```

> **A key reaches every user:** Any key can read and delete every scope, and the `/v1/memories/{id}` routes take any id. Keep keys on your backend, and put TLS in front of the server.

## Keyless means this machine only

A keyless server is reachable from any web page the user opens, so it answers only requests addressed to this machine by name (`localhost`, `127.0.0.1`, `[::1]` or a `*.localhost` name) that no other web page sent. Other requests get a 403. Clients that send no `Origin`, such as curl, SDKs and the TypeScript client, are not affected. If clients reach it by another name, such as `host.docker.internal` from a container, add the name with `--allowed-host` or `LLMSLIM_ALLOWED_HOSTS`.

> **Changed in 1.0:** 0.12 answered any `Host`. See [the upgrade guide](https://www.llmslim.app/docs/1.0/migrate-to-1-0#keyless-servers).

## Routes

Bodies and responses are JSON. Errors look like `{"error": {"type": "invalid_request", "message": "..."}}`. When Postgres or MongoDB can't be reached, the answer is a 503 with `"type": "store_unavailable"` and `Retry-After: 5`: retry it.

| Method and path | Body or query | Returns |
|---|---|---|
| `POST /v1/memories` | `messages` (a string, a `{role, content}` object or a list of them), at least one of `user_id`, `agent_id`, `run_id`, optional `timestamp`, `metadata` | `201 {"items": [...]}`, the stored messages |
| `GET /v1/memories` | `?user_id=&agent_id=&run_id=&since=&until=&limit=100&offset=0` | `{"items", "total", "offset", "limit"}`, oldest first |
| `GET /v1/memories/{id}` |  | One message |
| `PATCH /v1/memories/{id}` | `content` and/or `metadata` | The updated message |
| `DELETE /v1/memories/{id}` |  | `{"deleted": 1}` |
| `DELETE /v1/memories` | `?user_id=` (or `agent_id`, `run_id`; one is required) | `{"deleted": n}` |
| `POST /v1/memories/search` | `query`, the scope, optional `budget`, `relevance` (`"lexical"` or `"semantic"`), `since`, `until`, `explain` | `{"text", "tokens", "budget", "history_tokens", "sessions_total", "sessions_kept", "turns": [...]}`, and `"explanation"` with `"explain": true` ([guide](https://www.llmslim.app/docs/1.0/explain)) |
| `POST /v1/context/fit` | `text`, `budget` (default 2000), optional `query` | `{"text", "tokens", "original_tokens"}`, within about 2% of the budget for any text |
| `GET /v1/info` |  | Name, version and budgets |
| `POST /v1/chat/completions`, `GET /v1/models` | An OpenAI chat-completions request | The upstream's answer, with memory; 404 unless started with `--upstream-url` ([experimental](https://www.llmslim.app/docs/1.0/openai-compatible-endpoint)) |
| `GET /healthz` |  | `{"status": "ok"}`, without a key |

## Options

Flags win over environment variables.

| Flag | Environment variable | Default |
|---|---|---|
| `--host` | `LLMSLIM_HOST` | `127.0.0.1` |
| `--port` | `LLMSLIM_PORT` | `8080` |
| `--db` (a SQLite path or a database URL) | `LLMSLIM_MEMORY_DB` | `~/.llmslim/memory.db` |
| `--api-key` (repeatable) | `LLMSLIM_API_KEYS` (comma-separated) | none |
| `--budget` |  | `2000` tokens for search |

To run several processes or machines on one memory, point `--db` at Postgres: see [Storage backends](https://www.llmslim.app/docs/1.0/storage-backends).

## From Python

`create_app` gives you the ASGI app, to run with any ASGI server or mount in your own.

app.py:

```python
from llmslim.memory import Memory
from llmslim.server import create_app

app = create_app(Memory("memory.db"), api_keys=["<a key of 16+ characters>"])  # any ASGI server can run it
```

## FAQ

### Can I call it from a browser?

No. A key gives full access to every user's memory, so call the server from your backend, and map your own users to `user_id` there.

### Does the server call a model?

Not for memory or `fit`: they run no model, and nothing leaves your infrastructure.

### Does it speak TLS?

No, plain HTTP. Put a reverse proxy or load balancer that terminates TLS in front of it.

## Related

- [TypeScript quickstart](https://www.llmslim.app/docs/1.0/quickstart-typescript.md)
- [OpenAI-compatible endpoint](https://www.llmslim.app/docs/1.0/openai-compatible-endpoint.md)
- [Storage backends](https://www.llmslim.app/docs/1.0/storage-backends.md)

Canonical page: https://www.llmslim.app/docs/1.0/quickstart-http