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. Requires Agency plan or higher (same as MCP).

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 sources
response = client.responses.create(
    model="catalogian-1",
    input="list my sources",
    tool_choice={"type": "function", "name": "list_sources"},
    tools=[{
        "type": "function",
        "name": "list_sources",
        "description": "List all feed sources for the current user",
    }],
)

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: '{"sourceSlug": "my-feed"}'

Available tools

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

Tool	Description
`list_sources`	List all feed sources
`get_source_by_slug`	Look up a source by slug
`snapshot_schema`	Get field structure of current snapshot
`get_snapshot_rows`	Browse current feed rows (paginated)
`sample_snapshot`	Random or stratified sample from a feed snapshot. Use `stratifyBy` to get representative rows across brand, category, or any field.
`profile_snapshot`	Feed-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 delta events (what changed, when)
`get_delta_rows`	Row-level before/after data for a delta event
`compare_snapshots`	Diff two snapshots over time
`download_snapshot`	Export full feed 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	Needs MCP client or `mcp-remote`	No special library needed — standard HTTP
Tools	Same 16 tools	Same 16 tools

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