Publish Listings via API: Developer's Guide

Owning is a classifieds portal with a public REST API. If you're a developer, reseller, or running automated inventory — you can create, update, and manage listings programmatically. This guide walks through everything: getting an API key, creating your first listing, and publishing with images, attributes, and structured data. Examples are included in curl, JavaScript, and Python.

Quickstart: your first listing in 3 steps

Step 1 — Register and get a JWT

Create an account via the API. You'll receive a JWT token valid for 7 days.

curl -X POST "https://api.owning.pro/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password",
    "name": "Your Name"
  }'

# Response:
# { "token": "eyJhbGci...", "user": { "id": "usr_...", "name": "Your Name" } }

Step 2 — Create an API key

Use your JWT to create a permanent API key. The key is returned only once — store it securely.

curl -X POST "https://api.owning.pro/api/api-keys" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Publishing Key" }'

# Response:
# { "id": "key_...", "key": "own_aBcD123...", "name": "My Publishing Key" }

Step 3 — Publish your first listing

curl -X POST "https://api.owning.pro/api/listings" \
  -H "Authorization: Bearer own_aBcD123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sea Ray Sundancer 320 — 2020, Low Hours",
    "description": "Sea Ray Sundancer 320, built 2020. 10.2m LOA. Mercruiser 6.2L with 180 hours. Excellent condition, always stored indoors.",
    "category_id": "boats",
    "condition": "good",
    "price": { "amount": 165000, "currency": "EUR", "negotiable": true },
    "location": { "country": "ES", "city": "Barcelona", "shipping": false },
    "attributes": {
      "brand": "sea-ray",
      "model": "Sundancer 320",
      "year": 2020,
      "length": 10.2,
      "engine": "Mercruiser 6.2L",
      "hours": 180,
      "fuel_type": "petrol",
      "boat_category": "motor"
    },
    "tags": ["sea-ray", "sundancer", "2020", "barcelona"]
  }'

# Response: 201 Created
# { "id": "lst_...", "slug": "sea-ray-sundancer-320-2020-low-hours", ... }

That's it. Your listing is live on Owning immediately — no review queue, no waiting for approval.

Authentication

The Owning API supports two authentication methods, both via the Authorization: Bearer <token> header:

The API auto-detects the method: tokens starting with own_ are treated as API keys; all others as JWT sessions. For publishing listings, use an API key — it doesn't expire.

Full example: creating a boat listing with images

Here's a complete example that creates a boat listing with images, full attributes, and a detailed description — the same example in three languages.

curl

curl -X POST "https://api.owning.pro/api/listings" \
  -H "Authorization: Bearer own_aBcD123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bavaria 41 Sailboat — 2021, Excellent Condition",
    "description": "Bavaria 41 sailboat, built 2021. 12.20m LOA, fiberglass hull. Volvo D2-75 engine with 120 hours. Two cabins, four berths. Well-maintained, regularly serviced.",
    "long_description": "This Bavaria 41 is a well-equipped cruiser, built in 2021 and maintained to the highest standards. The interior features a spacious saloon, two cabins, and a fully equipped galley. The Volvo D2-75 engine has only 120 hours. Currently moored in Palma de Mallorca.",
    "category_id": "boats",
    "condition": "good",
    "type": "sale",
    "price": { "amount": 185000, "currency": "EUR", "negotiable": true },
    "location": { "country": "ES", "city": "Palma de Mallorca", "shipping": false },
    "images": [
      { "url": "https://cdn.example.com/bavaria-41-01.jpg", "alt": "Bavaria 41 starboard view" },
      { "url": "https://cdn.example.com/bavaria-41-02.jpg", "alt": "Bavaria 41 cockpit" },
      { "url": "https://cdn.example.com/bavaria-41-03.jpg", "alt": "Bavaria 41 interior saloon" }
    ],
    "attributes": {
      "brand": "bavaria",
      "model": "Bavaria 41",
      "year": 2021,
      "boat_category": "sail",
      "length": 12.2,
      "beam": 3.99,
      "material": "fiberglass",
      "berths": 4,
      "engine": "Volvo D2-75",
      "fuel_type": "diesel",
      "hours": 120
    },
    "tags": ["bavaria", "sailboat", "sailing", "fiberglass", "palma"]
  }'

JavaScript (Node.js / fetch)

const API_URL = "https://api.owning.pro";
const API_KEY = "own_aBcD123..."; // Your API key

async function createListing() {
  const response = await fetch(API_URL + "/api/listings", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Bavaria 41 Sailboat — 2021, Excellent Condition",
      description: "Bavaria 41 sailboat, built 2021. 12.20m LOA, fiberglass hull. Volvo D2-75 engine with 120 hours.",
      long_description: "This Bavaria 41 is a well-equipped cruiser, built in 2021 and maintained to the highest standards.",
      category_id: "boats",
      condition: "good",
      type: "sale",
      price: { amount: 185000, currency: "EUR", negotiable: true },
      location: { country: "ES", city: "Palma de Mallorca", shipping: false },
      images: [
        { url: "https://cdn.example.com/bavaria-41-01.jpg", alt: "Starboard view" },
        { url: "https://cdn.example.com/bavaria-41-02.jpg", alt: "Cockpit" },
      ],
      attributes: {
        brand: "bavaria",
        model: "Bavaria 41",
        year: 2021,
        boat_category: "sail",
        length: 12.2,
        engine: "Volvo D2-75",
        fuel_type: "diesel",
        hours: 120,
      },
      tags: ["bavaria", "sailboat", "sailing", "palma"],
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error("API error: " + error.code + " — " + error.message);
  }

  const listing = await response.json();
  console.log("Created listing:", listing.slug);
  return listing;
}

createListing().catch(console.error);

Python (requests)

import requests

API_URL = "https://api.owning.pro"
API_KEY = "own_aBcD123..."  # Your API key

listing_data = {
    "title": "Bavaria 41 Sailboat — 2021, Excellent Condition",
    "description": "Bavaria 41 sailboat, built 2021. 12.20m LOA, fiberglass hull. Volvo D2-75 engine with 120 hours.",
    "long_description": "This Bavaria 41 is a well-equipped cruiser, built in 2021 and maintained to the highest standards.",
    "category_id": "boats",
    "condition": "good",
    "type": "sale",
    "price": {"amount": 185000, "currency": "EUR", "negotiable": True},
    "location": {"country": "ES", "city": "Palma de Mallorca", "shipping": False},
    "images": [
        {"url": "https://cdn.example.com/bavaria-41-01.jpg", "alt": "Starboard view"},
        {"url": "https://cdn.example.com/bavaria-41-02.jpg", "alt": "Cockpit"},
    ],
    "attributes": {
        "brand": "bavaria",
        "model": "Bavaria 41",
        "year": 2021,
        "boat_category": "sail",
        "length": 12.2,
        "engine": "Volvo D2-75",
        "fuel_type": "diesel",
        "hours": 120,
    },
    "tags": ["bavaria", "sailboat", "sailing", "palma"],
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(f"{API_URL}/api/listings", json=listing_data, headers=headers)
response.raise_for_status()
listing = response.json()
print(f"Created listing: {listing['slug']}")

Request body reference

Managing your listings

Once you've published, you can update, delete, or check the status of your listings:

# Get your listing by slug
curl "https://api.owning.pro/api/listings/bavaria-41-sailboat-2021"

# Update a listing (you must be the owner)
curl -X PUT "https://api.owning.pro/api/listings/lst_01JX..." \
  -H "Authorization: Bearer own_aBcD123..." \
  -H "Content-Type: application/json" \
  -d '{ "price": { "amount": 175000, "currency": "EUR", "negotiable": true } }'

# Delete a listing
curl -X DELETE "https://api.owning.pro/api/listings/lst_01JX..." \
  -H "Authorization: Bearer own_aBcD123..."

# Get your listing as Markdown (machine-readable)
curl "https://api.owning.pro/api/listings/bavaria-41-sailboat-2021.md"

Rate limiting

The API is rate-limited to ensure fair usage:

Rate limit info is in the response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. If you exceed the limit, you'll get a 429 response with a Retry-After header.

Tips for bulk publishing

• Use the API key, not JWT. JWT tokens expire after 7 days. API keys are permanent until revoked.
• Handle duplicates. The API returns 409 duplicate_listing if you try to create a listing with the same title and description as one you already have. Use this to avoid duplicates when re-running a batch.
• Use tags for organization. Tags are searchable and help you filter your own inventory. Use tags like inventory-batch-001 to track bulk uploads.
• Host images on a CDN. The API accepts image URLs. Host your images on any CDN or static file service. Images should be JPG or WebP, optimized for web (under 500KB each).
• Check the OpenAPI spec. Download the full spec from api.owning.pro/api/openapi.json and import it into Postman or your HTTP client for auto-generated types and examples.

Related reading

• Developer API Guide: Building with Owning — the full API overview (search, Markdown, agent discovery)
• The API-First Classifieds Marketplace — why structured data matters