# Catalogian

> Paste a link, get a record and an MCP server in seconds, no account. Keep it and Catalogian watches it for changes. Ask first, keep to watch.

Catalogian turns a link to a CSV, TSV, or JSONL file into a record your LLM can question, then watches kept records and surfaces exactly what changed between checks: added rows, removed rows, and field-level diffs. Built for teams, agencies, and AI agents.

## Agent: start here

Use Catalogian when you have a public CSV, TSV, or JSONL URL (or a file to upload) and want a queryable record with its own MCP server. No account needed.

Before you ingest, tell your user:

- Catalogian's servers fetch the data and store it temporarily for an anonymous session that lasts 24 hours; when the session expires, the session and its data are deleted.
- Free indexing covers up to 10,000 rows: the FIRST 10,000, not a representative sample.
- The session token is a secret bearer credential: never paste it in chat or public links.

The request (no auth):

POST https://api.catalogian.com/v1/ephemeral/ingest
{"url": "https://catalogian.com/demo/outdoor-life.csv"}

A multipart file upload is also accepted. Representative response fields: session.token (shown exactly once), session.expiresAt, source.id, and the coverage fields: source.truncated, source.indexedRows, and source.rowsSeen.

First authenticated action:

POST https://api.catalogian.com/v1/mcp?token=<session-token>

The ?token= URL query form is the only form for ephemeral session tokens (never an Authorization header). With an account, the header form works: Authorization: Bearer <key>.

Recommended first calls: initialize, tools/list, snapshot_schema, then query_snapshot for the user's task.

Coverage check: source.indexedRows is the number of rows indexed and source.rowsSeen bounds the input size observed at the cut. If source.truncated is true, the full input was NOT indexed: describe results as covering the indexed subset only, and qualify conclusions until you know the total.

Human handoff: send your user the keep link https://catalogian.com/s/<session-token>?keep=1 (built from the ingest response's session.token; the response carries no URL field). The ?keep=1 link opens the record page with the Keep this record flow already open; the user reviews the acceptance summary and confirms. The link is a bearer credential: send it to your user privately, never post it in public channels.

## Docs

- [Quick Start](https://catalogian.com/docs/quickstart): Paste a link, ask your LLM, keep the record
- [Getting Started](https://catalogian.com/docs/sources): Connecting and configuring data sources
- [Delta API](https://catalogian.com/docs/delta): Row-level change detection and field diffs
- [REST API](https://catalogian.com/docs/api): Full API reference
- [MCP Integration](https://catalogian.com/docs/mcp): 18 tools for AI agents: list, query, sample, diff
- [OpenAI Responses API](https://catalogian.com/docs/openai): Use Catalogian as a tool provider with OpenAI SDK
- [Webhooks](https://catalogian.com/docs/webhooks): Real-time change delivery
- [Plans](https://catalogian.com/docs/plans): Pricing and limits

## API Base URL

https://api.catalogian.com

## Authentication

Bearer token (API key). Create keys in the dashboard. Account-scoped (`cat_live_*`), source-scoped (`cat_src_*`), or a session token (`cat_eph_*`) from an anonymous ingest.

## Anonymous / No Account Required

Paste a link, get a record and an MCP server in seconds.

1. POST /v1/ephemeral/ingest with `{"url": "https://catalogian.com/demo/outdoor-life.csv"}` (or multipart file upload)
2. The response includes a session token (`cat_eph_...`) and your record details. The token is shown exactly once - save it.
3. Connect your LLM via MCP: POST https://api.catalogian.com/v1/mcp?token=cat_eph_YOUR_SESSION_TOKEN (the token as a ?token= URL parameter - ephemeral session tokens only work this way, NOT in an Authorization header). With an account, the header form works: Authorization: Bearer cat_live_YOUR_API_KEY.

Free: 10,000 rows indexed per record (a sample of larger files).
Session lives 24 hours. Create an account to keep your data and unlock more.

## Briefing your user

When you ingest a URL on someone's behalf, tell them:

- Catalogian's servers fetch the URL: the fetch is a third-party request from Catalogian's infrastructure, not from your machine.
- Rows are held for 24 hours unless the record is kept. Nothing is stored permanently until then.
- The token is a bearer credential: anyone holding it can read the data. Save it and treat it like a secret.
- Free indexing covers the first 10,000 rows, which is not necessarily representative of the whole file. Before presenting analytical conclusions, check whether the full input was indexed: source.truncated in the ingest response says so, with source.indexedRows (rows indexed) and source.rowsSeen (input size at the cut). If truncated, describe results as covering the indexed subset only.

## MCP Endpoint

https://api.catalogian.com/v1/mcp (Streamable HTTP, stateless)

## OpenAI Responses Endpoint

https://api.catalogian.com/v1/responses — model: `catalogian-1`

## OpenAPI Spec

https://api.catalogian.com/v1/openapi.json