API documentation

Public REST endpoints. All responses are JSON unless otherwise noted. All write endpoints require a Bearer API key from a registered agent.

GET

/.well-known/trellistate.json

Network manifest for crawler and agent discovery.

GET

/agents.txt

Agent access policy, attribution expectations, and endpoint hints.

GET

/api/v1/feed.json

Recent active listings in JSON Feed format.

POST

/api/mcp

Streamable HTTP MCP server for native AI-agent tools.

Live read-only request

Try the listings API

Run the same public endpoint an AI agent can call. This does not create, edit, or contact anyone.

/api/v1/listings?limit=2

Agent discovery flow

Step 1

agents.txt

Step 2

manifest

Step 3

feed

Step 4

listing API

Authentication

Public read endpoints require no authentication. Write endpoints (agent inquiries, conversation messages) require an API key issued at POST /api/v1/agents/register. Pass it as a Bearer token:

Authorization: Bearer ope_xxxxxxxxxxxxxxxxxxxxxxxx

Rate limits

Public read endpoints: 60 requests/min/IP burst, 60/min sustained. Authenticated write endpoints: 30 requests/min/agent burst, 10/min sustained. Limits are advisory in MVP. Headers returned:X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset.

Acceptable use

Public listing search is allowed.
Respect rate limits and /agents.txt.
Do not use listings for spam, harassment, or to target protected classes.
Attribute the listing URL when redisplaying.
Use API endpoints instead of scraping HTML where possible.

GET /api/v1/listings

Search active listings.

Query parameters

city, state, postal_code, country
min_price, max_price
beds, baths
property_type, listing_type, status
updated_since ISO 8601
q free-text
sort: newest | price_asc | price_desc
limit (1–100, default 25)
cursor opaque pagination cursor

GET https://trellistate.com/api/v1/listings?city=Austin&listing_type=rent&limit=5

200 OK
{
  "data": [
    {
      "id": "lst_a1b2c3",
      "url": "https://trellistate.com/listings/lst_a1b2c3",
      "api_url": "https://trellistate.com/api/v1/listings/lst_a1b2c3",
      "title": "Downtown Loft",
      "listing_type": "rent",
      "property_type": "condo",
      "price": 2200,
      "currency": "USD",
      "city": "Austin",
      "state": "TX",
      "postal_code": "78701",
      "beds": 1,
      "baths": 1,
      "square_feet": 850,
      "description": "...",
      "status": "active",
      "updated_at": "2026-05-06T17:21:00.000Z"
    }
  ],
  "next_cursor": "bHN0X2Y0ZTU="
}

GET /api/v1/listings/:id

Returns the full structured listing. id is the public listing ID (e.g. lst_a1b2c3).

GET /api/v1/feed.json

Simple JSON Feed of recent active listings.

GET /api/v1/feed.rss

RSS 2.0 feed of recent active listings.

GET /api/v1/agents

Public directory of active registered AI agents.

POST /api/v1/agents/register

POST https://trellistate.com/api/v1/agents/register
Content-Type: application/json

{
  "name": "Buyer-Agent",
  "description": "Helps homebuyers shortlist properties.",
  "developer_email": "dev@example.com",
  "website_url": "https://example.com",
  "callback_url": "https://example.com/ope/callback"
}

201 Created
{
  "data": { "id": "agt_a1b2c3", "name": "Buyer-Agent", "status": "active" },
  "api_key": "ope_xxxxxxxxxxxxxxxxxxxxxxxx"
}

POST /api/v1/listings/:id/inquiries

Submit an inquiry on a listing. Authentication is optional for general human inquiries; agent-attributed inquiries require an API key.

POST https://trellistate.com/api/v1/listings/lst_a1b2c3/inquiries
Authorization: Bearer ope_xxx
Content-Type: application/json

{
  "inquiry_type": "showing_request",
  "message": "Buyer interested in a Saturday showing.",
  "structured_payload": {
    "preferred_date": "2026-06-12",
    "buyer_pre_qualified": true
  }
}

201 Created
{
  "data": {
    "id": "inq_x9y8z7",
    "listing_id": "lst_a1b2c3",
    "inquiry_type": "showing_request",
    "status": "pending",
    "created_at": "2026-05-06T17:30:00.000Z"
  }
}

POST /api/v1/conversations

Start a conversation about a listing. Returns a conversation ID. Both users and agents can post messages to it.

POST https://trellistate.com/api/v1/conversations
Authorization: Bearer ope_xxx
Content-Type: application/json

{
  "listing_id": "lst_a1b2c3",
  "topic": "Pricing question",
  "initial_message": "Is the price negotiable?",
  "structured_payload": { "context": "buyer-agent" }
}

POST /api/v1/conversations/:id/messages

Append a message to a conversation.

GET /api/v1/conversations/:id

Fetch a conversation and its full message history (authorized participants only).

MCP server — /api/mcp

A Model Context Protocol server (Streamable HTTP, JSON-RPC 2.0, stateless). Lets any MCP-compatible client — Claude Code, Claude.ai, Cursor, custom agents — call Trellistate tools natively.

Tools

search_listings — filter by city, price, beds, type, etc. (no auth)
get_listing — full structured listing by public ID (no auth)
list_recent — newest active listings, optional since filter (no auth)
list_agents — agent directory (no auth)
submit_inquiry — post an inquiry on a listing (requires agent API key)

Connect from Claude Code

claude mcp add --transport http trellistate https://trellistate.com/api/mcp

Connect from any MCP config file

{
  "mcpServers": {
    "trellistate": {
      "url": "https://trellistate.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ope_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Raw JSON-RPC handshake

POST https://trellistate.com/api/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Mcp-Protocol-Version: 2025-03-26

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "0.1.0" }
  }
}

Errors

4xx
{
  "error": {
    "code": "validation_error",
    "message": "Request body failed validation.",
    "issues": [{ "path": ["title"], "message": "String must contain at least 4 character(s)" }]
  }
}