Developer API Guide: Building with Owning

Owning is a classifieds portal with a public API. Every listing serves JSON, Markdown, and HTML from the same endpoint — no scraping, no fragile HTML parsing. This guide walks through everything you need to start building with the Owning API: authentication, search, filtering, structured data formats, and agent-native discovery features.

Quickstart

Public read endpoints require no authentication. You can make your first request right now:

# Search for motor yachts
curl "https://api.owning.pro/api/listings?category=boats&attr[boat_category]=motor&limit=5"

# Get a single listing as JSON
curl "https://api.owning.pro/api/listings/bavaria-s36-coupe"

# Get the same listing as Markdown
curl "https://api.owning.pro/api/listings/bavaria-s36-coupe.md"

That's it. No API key needed for read operations. For write operations (creating listings, managing your inventory), you'll need an API key.

Getting an API key

1. Register an account via POST /api/auth/register or log in via POST /api/auth/login. You'll receive a JWT token.
2. Create an API key: POST /api/api-keys with your JWT in the Authorization header.
3. The response returns your API key once (format: own_...). Store it securely — it can't be retrieved again.
4. Use the key in all authenticated requests: Authorization: Bearer own_yourkey

Main endpoints

The API is organized around listings, categories, asset types, and ingestion. Here's the full reference:

The full interactive API reference is at api.owning.pro/api/docs (Scalar UI — test endpoints in your browser).

Searching and filtering listings

The GET /api/listings endpoint supports rich filtering via query parameters:

# Search by text query
curl "https://api.owning.pro/api/listings?q=sunseeker&limit=10"

# Filter by category
curl "https://api.owning.pro/api/listings?category=boats&limit=10"

# Filter by structured attributes
curl "https://api.owning.pro/api/listings?category=boats&attr[brand]=bavaria&limit=10"
curl "https://api.owning.pro/api/listings?category=boats&attr[boat_category]=sail&limit=10"

# Filter by price range
curl "https://api.owning.pro/api/listings?min_price=50000&max_price=150000&limit=10"

# Sort by newest or price
curl "https://api.owning.pro/api/listings?sort=newest&limit=10"
curl "https://api.owning.pro/api/listings?sort=price_asc&limit=10"

# Paginate
curl "https://api.owning.pro/api/listings?category=boats&limit=20&page=2"

The response includes a pagination object with total, page, pages, and limit — use these to iterate through all results.

Agent-native features

Owning is built to be machine-readable from the ground up. Three features make it easy for automated systems to discover and use the API:

1. Agent discovery: /.well-known/ai.json

The discovery document at /.well-known/ai.json tells any automated system what the API offers and where to find documentation:

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

It includes the API base URL, available endpoints, schema links, and the OpenAPI spec location. Any system that follows well-known discovery conventions can find and use the Owning API automatically.

2. Multiple response formats

Every listing is available in three formats from the same endpoint:

• JSON — /api/listings/{slug} — structured data for applications and integrations
• Markdown — /api/listings/{slug}.md — lightweight text for pipelines, summaries, or feeding into LLMs
• HTML — the web page at owning.pro/listings/{slug} — for human browsing

The full catalog is also available as Markdown at /api/listings.md — useful for bulk processing.

3. OpenAPI spec

The API has a complete OpenAPI 3.0 specification:

# Download the spec
curl "https://api.owning.pro/api/openapi.json" -o owning-openapi.json

# Import into Postman, Swagger, Insomnia, or any OpenAPI-compatible tool

The interactive Scalar UI at api.owning.pro/api/docs lets you test every endpoint in the browser with live requests.

Examples

Search for boats by brand

curl "https://api.owning.pro/api/listings?category=boats&attr[brand]=sunseeker&limit=5" | jq '.results[] | {title, price: .price.amount, brand: .attributes.brand}'

Get a listing as Markdown

curl "https://api.owning.pro/api/listings/bavaria-s36-coupe.md"

Returns a clean Markdown document with the listing title, price, specifications, and description — ready to embed in any text-based pipeline.

Publish a listing

curl -X POST "https://api.owning.pro/api/listings" \
  -H "Authorization: Bearer own_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bavaria S36 Coupe — 2018",
    "category": "boats",
    "price": {"amount": 218000, "currency": "EUR", "negotiable": true},
    "condition": "used",
    "description": "Well-maintained Bavaria S36 Coupe...",
    "attributes": {
      "brand": "bavaria",
      "year": 2018,
      "length": 11,
      "boat_category": "motor",
      "engine": "2 x 220 PS"
    }
  }'

Rate limiting and authentication

All endpoints are rate-limited with sliding per-minute windows:

Every response includes rate limit headers so you can monitor your usage:

• X-RateLimit-Limit — max requests per window
• X-RateLimit-Remaining — remaining requests in current window
• X-RateLimit-Reset — seconds until window resets

If you exceed the limit, you'll get HTTP 429 with a Retry-After header telling you how many seconds to wait.

Best practices

• Use pagination: The API caps at 100 results per request. Use the page parameter to iterate through all results.
• Cache responses: Listing data doesn't change every second. Cache responses for 5–15 minutes to reduce API calls.
• Use structured filters: Filter by attr[...] parameters instead of fetching everything and filtering client-side. It's faster and uses fewer rate limit tokens.
• Store API keys securely: Keys are shown once at creation. Use environment variables or a secrets manager — never hardcode them.
• Handle 429 gracefully: Implement exponential backoff when you receive rate limit errors.

Related reading

• The API-First Classifieds Marketplace — why we built Owning with structured data from day one
• Owning: A Modern Classifieds — the launch announcement