OpenAI SDK & Responses API

Catalogian exposes a POST /v1/responses endpoint that implements the OpenAI Responses API specification. Any client built with the OpenAI SDK — or any framework that speaks the Responses API format — can use Catalogian as a data tool provider without any custom integration work.

Connecting

POST https://api.catalogian.com/v1/responses
Authorization: Bearer <your-api-key>
Content-Type: application/json

Use a Catalogian API key (cat_live_...) from the Keys page in your dashboard. API keys unlock with any one paid record; MCP is on every rung of the ladder.

OpenAI Python SDK

Point the OpenAI client at Catalogian and call tools directly:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.catalogian.com/v1",
    api_key="cat_live_your_key_here",
)

# List all your records
response = client.responses.create(
    model="catalogian-1",
    input="list my records",
    tool_choice={"type": "function", "name": "list_records"},
    tools=[{
        "type": "function",
        "name": "list_records",
        "description": "List all records monitored for this account. Start here to discover available recordId and recordSlug values needed by every other tool. Returns id, slug, name, url, status, format, lastCheckedAt, and vanityUrl for each record. Use the slug with other tools for more readable calls; a record whose slug is null has no slug, so use its id.",
    }],
)

for item in response.output:
    if hasattr(item, "content"):
        for part in item.content:
            print(part.text)

How tool dispatch works

This endpoint is a tool provider, not a language model. It does not generate text or decide which tool to call — your LLM does that, then invokes Catalogian to execute the tool.

• Tool dispatch is explicit — specify tool_choice: { "type": "function", "name": "<tool_name>" }
• tool_choice: "auto" or "required" returns a list of available tools instead of calling one
• The intent is for a real LLM (in your app or agent framework) to decide which tool to call, then invoke Catalogian to execute it
• Pass tool arguments as a JSON string in the input field: input: '{"recordSlug": "west-coast-earthquakes"}'

Available tools

All 18 tools are shared with the MCP endpoint. Each can be called via tool_choice:

Tool	Description
`list_records`	List all records monitored for this account
`get_record_by_slug`	Look up a record by slug
`list_editions`	List the editions of a record: every ingest that created a new version, with row counts and change summaries
`get_edition_diff`	Diff two editions: rows added, changed, or removed, with field-level before and after
`snapshot_schema`	Get field structure of current snapshot
`get_snapshot_rows`	Browse current record rows (paginated)
`sample_snapshot`	Random or stratified sample from a record snapshot. Use `stratifyBy` to get representative rows across any set of fields.
`profile_snapshot`	Record-level quality report: field cardinality, null rates, value distributions, type hints, and stratification recommendations.
`search_snapshot`	Full-text search across all row fields
`filter_snapshot_rows`	Filter rows by field conditions
`query_snapshot`	Aggregations: count, distinct, group_by, min/max/avg/sum
`get_delta`	Get change events for a record (what changed, when)
`get_delta_rows`	Row-level before/after data for a change event
`compare_snapshots`	Diff two snapshots over time
`download_snapshot`	Export full snapshot as CSV/JSON (pre-signed URL)
`download_filtered_snapshot`	Export filtered subset as CSV/JSON
`get_health`	Health score and diagnostic indicators
`list_tools`	List all available tools with descriptions

Using with agent frameworks

Any framework that speaks the OpenAI Responses API format can use Catalogian as a tool provider out of the box — including the OpenAI Agents SDK, LangChain, and the Vercel AI SDK. Point the framework's HTTP tool client at https://api.catalogian.com/v1/responses with your API key and tools are available immediately.

Differences from MCP

	MCP (`/v1/mcp`)	Open Responses (`/v1/responses`)
Protocol	Model Context Protocol (Streamable HTTP)	OpenAI Responses API (HTTP/JSON)
Best for	Claude Desktop, Cursor, MCP-native clients	Custom agent code, OpenAI SDK users
Client library	Claude, ChatGPT, and Cursor connect natively; other agents use `mcp-remote`	No special library needed — standard HTTP
Tools	Same 18 tools	Same 18 tools

Both endpoints use the same API key. Choose whichever fits your stack — or use both.