> For the complete documentation index, see [llms.txt](https://docs.gitloom.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gitloom.cloud/api-reference/overview.md). # Overview Base URL, authentication, the two error shapes, and where every route lives. GitLoom stores what an agent learns about a user as markdown in a git repository — one repository per namespace — and returns it when a later question needs it. This space is the machine-readable contract; [docs.gitloom.cloud/documentation](https://docs.gitloom.cloud/documentation/) is the narrative version, written to be read start to end. ### Base URL ``` https://api.gitloom.cloud ``` #### GET /health The only route that needs no credential. ```json {"status": "ok"} ``` #### GET /v1/whoami Confirms a credential is valid and reports what it resolves to — the first call worth making when wiring up a client, since it fails for exactly one reason. ```bash curl -s "$GITLOOM_API/v1/whoami" -H "Authorization: Bearer $GITLOOM_KEY" ``` ```json {"account": "acme", "auth": "api_key", "env": "live"} ``` ### Authentication Two credential types reach every endpoint: {% tabs %} {% tab title="API key" %} ``` Authorization: Bearer gl_live_3f9a2b7c1d4e6f80_kQ8vN2xR7mZpLd3Wc0Ty5Ub9Aj1Hs4Ge ``` Server-side only — account-wide read and write over every namespace. Create one from [app.gitloom.cloud](https://app.gitloom.cloud/); it is shown once, at creation. {% endtab %} {% tab title="Dashboard session" %} ``` Authorization: Bearer ``` What the dashboard itself uses. Required for Keys and Licences — an API key calling either gets `403 dashboard_only`, so a leaked key cannot mint its own replacement. {% endtab %} {% endtabs %} {% hint style="info" %} **One error shape.** Every route returns `{"error": {"code", "message"}}`. Branch on `code`, which is stable; `message` is prose and may be reworded. Retrieval used to answer with a flat `{"error": "..."}` and no longer does. {% endhint %} ### Every route


Namespaces	Create and list namespaces.
Memories	Write, retrieve, and view the memory graph.
Vocabulary	Terms and abbreviations a namespace has learned.	Vocabulary
Skills	Procedural know-how, found by task.	Skills
Usage and billing	Consumption, wallet, recharge, subscribe.
Keys	API key lifecycle. Dashboard sessions only.
Licences	For running the CLI locally.
Conversations	Durable chat history with a context guarantee.
Logs	Recent request activity for the account.

[openapi.yaml](https://gitloom.cloud/docs/openapi.yaml) is the machine-readable contract for the deployed API and carries the full schemas and every status code. The pages here are written by hand against it, so where the two disagree the spec is right. See also: [Plans and pricing](https://docs.gitloom.cloud/documentation/content/pricing) for what `quota_exceeded`, `balance_exhausted` and `rate_limited` mean and how to clear each one; [Limits and behaviour](https://docs.gitloom.cloud/documentation/content/limits) for what is asynchronous and what nothing enforces yet. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.gitloom.cloud/api-reference/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.