---
title: "Tamloot — Public API"
description: "Tamloot’s public API gives your own tools read-only access to the contacts, sessions, transcripts, and notes in your Tamloot account."
canonical: "https://tamloot.cc/en/docs/developers/api"
last-updated: "2026-10-18"
---

# Public API

Tamloot’s public API gives your own tools read-only access to the contacts, sessions, transcripts, and notes in your Tamloot account.

## Start here

1. In Tamloot, open **Settings → API**.
2. Create an API key and copy it immediately. Tamloot only shows the full secret once.
3. Send it as a bearer token with every data request.

```bash
curl "https://api.tamloot.cc/v1/contacts?query=maya" \
  -H "Authorization: Bearer tml_live_your_key"
```

## API reference

- Base URL: `https://api.tamloot.cc/v1`
- OpenAPI description: [openapi.json](https://tamloot.cc/openapi.json)
- API catalog: [/.well-known/api-catalog](https://tamloot.cc/.well-known/api-catalog)
- Developer index: [Tamloot Developer Resources](https://tamloot.cc/en/developers)

## Rate limits

The API allows **10 requests per second** (burst 20). Every response declares that policy, so a client can pace itself instead of discovering the ceiling by hitting it:

| Header | Meaning | Sent on |
| --- | --- | --- |
| `RateLimit-Limit` | Requests allowed per one-second window | Every response |
| `RateLimit-Policy` | The policy, as `<limit>;w=<window seconds>` | Every response |
| `Retry-After` | Seconds to wait before retrying | `429` only |

A request over the limit is answered with `429 Too Many Requests` and a `Retry-After`. Wait that many seconds and retry.

There is deliberately no `RateLimit-Remaining` or `RateLimit-Reset`. The throttle is enforced at the edge, ahead of the application, so no single server can see your running total — a per-server count would report *more* budget than you actually have left. Pace against `RateLimit-Policy` and treat a `429` as the authoritative signal.

## Versioning and deprecation

The API is versioned in the path (`/v1`). Within a version, changes are additive only: new endpoints, new optional parameters, and new response fields. Clients should ignore fields they don't recognize.

Breaking changes ship only in a new version. When a version is retired, it keeps working for **at least 6 months** after the announcement on this page, and during that window every response from it carries a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) and a `Sunset` header with the shutdown date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)).

## Endpoints

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/contacts?query=` | Search contacts |
| GET | `/contacts/{contact_id}` | Get a contact and its context |
| GET | `/sessions` | Browse or search sessions |
| GET | `/sessions/{session_id}` | Get a session and notes |
| GET | `/sessions/{session_id}/transcript` | Get the transcript text |
| GET | `/notes?query=` | Search notes |

The API is read-only. Rotate or revoke a key at any time in **Settings → API**.

## Where to look next

- [Tamloot](https://tamloot.cc/en)
- [All guides](https://tamloot.cc/en/docs)
- [llms.txt](https://tamloot.cc/docs/llms.txt)
- [Sitemap](https://tamloot.cc/sitemaps/sitemap.xml)