Owning for AI Agents

Category: Developers Last updated: 2026-07-14

Owning is built API-first, with native support for AI agents and automated systems. Beyond the standard HTML web interface, every listing is available as structured JSON and lightweight Markdown — so agents can browse, search, read, and create listings without parsing HTML. This guide covers the three main ways to interact with Owning programmatically.

The three integration paths

Method	Best for	Auth required
REST API	Scripts, integrations, custom agents	API key for write operations
MCP server	Claude Desktop, Cursor, and other MCP clients	API key for write tools
Machine-readable formats	Quick reads, content pipelines	None for reads

Agent discovery: .well-known/ai.json

AI agents can discover Owning's capabilities by fetching the manifest file:

curl https://owning.pro/.well-known/ai.json

This returns a machine-readable description of the API — base URL, version, available endpoints, authentication methods, and supported response formats:

{
  "name": "Owning",
  "description": "Classifieds portal — buy and sell new and second-hand items",
  "api": {
    "base_url": "https://owning.pro/api",
    "version": "v1",
    "endpoints": {
      "listings": "/api/listings",
      "categories": "/api/categories",
      "schema": "/api/schema/listing",
      "auth": "/api/auth",
      "interactive_docs": "/api/docs",
      "openapi_spec": "/api/openapi.json"
    },
    "auth": {
      "type": "api_key",
      "header": "Authorization",
      "prefix": "Bearer"
    }
  },
  "formats": ["json", "markdown"]
}

Agents can use this to self-discover how to interact with the platform — no manual documentation reading required.

Using the REST API

The Owning API is standard REST with JSON responses. The base URL is https://api.owning.pro/api.

Searching listings

curl "https://api.owning.pro/api/listings?category=electronics&min_price=100&max_price=500&condition=good"

Supported filters include q (text search), category, min_price, max_price, condition, country, city, shipping, sort, page, limit, and attr[] for category-specific attributes.

Getting a single listing

# By slug
curl https://api.owning.pro/api/listings/canon-eos-rebel-t3i-dslr

# By ID
curl https://api.owning.pro/api/listings/lst_01KX8ZMGNVZ4BZXWGTJR7FNHH1

Authentication

Read endpoints are public. Write operations (creating listings, uploading images, contacting sellers) require an API key:

1. Register an account at owning.pro/register
2. Log in and create an API key via POST /api/api-keys with your JWT
3. The key starts with own_ — pass it in the Authorization header:

curl https://api.owning.pro/api/listings \
  -H "Authorization: Bearer own_your_api_key_here"

See Account & API Keys for full details on authentication, rate limits, and key management.

Interactive API documentation

The full interactive API reference is available at api.owning.pro/api/docs — a Scalar UI with try-it-out functionality for every endpoint. The OpenAPI spec is at /api/openapi.json.

Machine-readable formats: JSON and Markdown

Every listing is available in two machine-readable formats:

JSON

The default API response format. Returns all listing fields as structured data:

curl https://api.owning.pro/api/listings/canon-eos-rebel-t3i-dslr

Markdown

Append .md to any listing URL to get the Markdown version — perfect for AI agents that process text:

curl https://api.owning.pro/api/listings/canon-eos-rebel-t3i-dslr.md

The Markdown response includes YAML frontmatter with structured metadata (title, price, currency, condition, category, location) followed by the listing content in readable Markdown. No authentication required.

Markdown combines the best of both worlds: it's readable by humans and trivially parseable by machines. See Markdown & JSON Formats for full details.

The MCP server

For AI agents that support the Model Context Protocol (MCP), Owning provides a native MCP server at https://mcp.owning.pro/mcp. Instead of making raw API calls, the agent calls named tools and the MCP server handles the communication.

Connecting Claude Desktop

Add this to your Claude Desktop config file:

{
  "mcpServers": {
    "owning": {
      "url": "https://mcp.owning.pro/mcp",
      "transport": "streamable-http"
    }
  }
}

On macOS the config is at ~/Library/Application Support/Claude/claude_desktop_config.json. Restart Claude Desktop after saving.

Available tools

The MCP server exposes 10 tools:

Read tools (no auth required):

• search_listings — search and filter listings
• get_listing — get a single listing as JSON
• get_listing_markdown — get a single listing as Markdown
• list_categories — browse available categories
• get_asset_type — get a category's attribute schema

Write tools (API key required):

• create_listing — create a new listing draft
• upload_image — upload an image to a listing
• publish_listing — move a draft to active
• contact_seller — send a message to a seller
• manage_listing — edit, pause, or delete a listing

See the MCP Quickstart for configuration guides for Claude Desktop, Cursor, Windsurf, and other MCP clients, plus per-tool input/output examples.

Rate limits

API access is rate-limited to ensure fair usage:

Scope	Limit	Window
Unauthenticated reads	200 requests	per minute (per IP)
Authenticated reads	600 requests	per minute (per user/key)
Create listings	10	per day
Upload images	50	per day
Contact sellers	5	per hour
AI generate	5	per hour

If you need higher limits for a legitimate use case, contact hello@owning.pro.

Learn more

• MCP Quickstart — full configuration guides and tool examples
• Developer Onboarding Guide — complete API guide
• API Cookbook — 10 practical recipes
• Integration Examples — code in Python, JS, and cURL
• API Reference — complete endpoint documentation
• Markdown & JSON Formats — machine-readable formats in depth
• Account & API Keys — authentication and key management