Riferimento API

L'API di Owning.pro è un'API RESTful per cercare, sfogliare, creare e gestire annunci. Tutti gli endpoint restituiscono JSON; gli endpoint degli annunci supportano anche risposte Markdown. L'API è disponibile su https://api.owning.pro e proxy su https://owning.pro/api.

Riepilogo endpoint

* = autenticazione richiesta (JWT o API key)

Autenticazione

Gli endpoint di lettura pubblici (GET) non richiedono autenticazione. Le operazioni di scrittura (POST, PUT, DELETE, PATCH) richiedono autenticazione.

docsApi.authDesc2

• Token di sessione JWT — ottenuti via POST /api/auth/register o POST /api/auth/login. Validi per 7 giorni.
• API key — chiavi di lunga durata in formato own_..., create via POST /api/api-keys. Supportano permessi read, write e admin.

L'API rileva automaticamente il tipo di token: i token che iniziano con own_ sono trattati come API key; tutti gli altri come sessioni JWT.

Creazione di una API key

# 1. Register (or login if you have an account)
curl -X POST https://api.owning.pro/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepassword123","name":"Jane Doe"}'

# Response: { "user": {...}, "token": "eyJhbG...", "token_type": "bearer", "expires_in": 604800 }

# 2. Create an API key using the JWT
curl -X POST https://api.owning.pro/api/api-keys \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My Integration Key","permissions":"write"}'

# Response: { "id":"apk_...", "key":"own_aBcD123eFgH...", "key_prefix":"own_aBcD1", ... }
# The plaintext key is shown ONCE - store it securely.

# 3. Use the API key for all subsequent requests
curl https://api.owning.pro/api/listings \
  -H "Authorization: Bearer own_aBcD123eFgH..."

Rate Limits

Le risposte con rate limit restituiscono 429 Too Many Requests con error.code rate_limited.

Formati di risposta

Gli endpoint degli annunci supportano due formati di risposta:

• JSON (predefinito) — application/json. Restituisce oggetti annuncio strutturati.
• Markdown — text/markdown. Restituisce un documento Markdown leggibile da macchine con frontmatter YAML. Richiedilo aggiungendo .md all'URL o inviando Accept: text/markdown.

# JSON (default)
curl https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW

# Markdown - via .md suffix
curl https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW.md

# Markdown - via Accept header
curl https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW \
  -H "Accept: text/markdown"

Formato errori

Tutti gli errori restituiscono una struttura JSON coerente:

{
  "error": {
    "code": "not_found",
    "message": "Listing not found",
    "details": { "id": "lst_abc123" }
  }
}

Annunci

GET /api/listings

Cerca e filtra annunci con paginazione, ordinamento e filtri di attributi dinamici. Pubblico — nessuna auth richiesta.

Parametri query

Risposta di esempio

{
  "results": [
    {
      "id": "lst_01KX8G9BM7JKT48N9JZKJP12QW",
      "slug": "lagoon-400-s2-JP12QW",
      "title": "Lagoon 400 S2",
      "description": "Gebrauchtboot; Baujahr 2016",
      "category": { "id": "boats", "name": "Boats", "path": ["vehicles", "boats"] },
      "condition": "good",
      "type": "sale",
      "price": { "amount": 295000, "currency": "EUR", "negotiable": true },
      "location": { "country": "HR", "city": "Split", "shipping": false },
      "images": [{ "url": "https://static.owning.pro/images/...", "alt": "..." }],
      "attributes": { "beam": 7.25, "year": 2016, "brand": "lagoon", "length": 11.97 },
      "seller": { "id": "usr_...", "name": "Owning Marketplace", "type": "agent", "verified": false, "member_since": "2026-07-10" },
      "status": "active",
      "created_at": "2026-07-11T11:51:29.151Z",
      "updated_at": "2026-07-11T12:03:55.771Z",
      "expires_at": "2026-08-10T11:51:22.151Z",
      "views": 34,
      "tags": ["lagoon", "2016"],
      "meta": { "source": "scraped", "language": "en" }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 7668, "pages": 384 }
}

Esempio: Ricerca con filtri

# Search for boats between 50,000 and 150,000 EUR, sorted by price
curl "https://api.owning.pro/api/listings?category=boats&min_price=50000&max_price=150000&sort=price_asc&limit=10"

# Full-text search for "bavaria" in the boats category
curl "https://api.owning.pro/api/listings?q=bavaria&category=boats"

# Filter by brand attribute and length range
curl "https://api.owning.pro/api/listings?category=boats&attr[brand]=bavaria&attr[min_length]=10&attr[max_length]=15"

# Get listings in Spain with shipping available
curl "https://api.owning.pro/api/listings?country=ES&shipping=true"

Codici di stato

POST /api/listings

docsApi.createListingDesc

Corpo della richiesta

Esempio

curl -X POST https://api.owning.pro/api/listings \
  -H "Authorization: Bearer own_aBcD123eFgH..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Apple iPhone 13 128GB Blue",
    "description": "Apple iPhone 13 in blue, 128GB storage. Good condition with minor wear. Battery health 89%.",
    "category_id": "electronics",
    "condition": "good",
    "type": "sale",
    "price": { "amount": 399, "currency": "EUR", "negotiable": true },
    "location": { "country": "ES", "city": "Madrid", "shipping": true },
    "images": [{ "url": "https://static.owning.pro/images/tmp/iphone13-1.webp", "alt": "iPhone 13 front" }],
    "attributes": { "brand": "Apple", "model": "iPhone 13", "storage": "128GB" },
    "tags": ["iphone", "apple", "smartphone", "128gb"]
  }'

Codici di stato

GET /api/listings/{id}

Ottieni un singolo annuncio per ID o slug. Pubblico. La risposta di dettaglio include long_description (se disponibile), non presente nelle risposte elenco.

Esempio

curl https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW

# Returns full listing JSON with long_description, all attributes, all images

GET /api/listings/{id}.md

Ottieni un annuncio come Markdown leggibile da macchine. Pubblico. Il Markdown include frontmatter YAML con metadati chiave, seguito da sezioni strutturate.

Risposta di esempio

---
id: "lst_01KX8G9BM7JKT48N9JZKJP12QW"
slug: "lagoon-400-s2-JP12QW"
title: "Lagoon 400 S2"
price: 295000
currency: "EUR"
negotiable: true
condition: "good"
type: "sale"
status: "active"
category:
  id: "boats"
  name: "Boats"
  path: ["vehicles", "boats"]
location:
  country: "HR"
  city: "Split"
  shipping: false
seller:
  id: "usr_01KX6SQGZYHSBDCC3D6GSBNFV8"
  name: "Owning Marketplace"
  type: "agent"
  verified: false
  member_since: "2026-07-10"
images:
  - url: "https://static.owning.pro/images/..."
    alt: "Lagoon 400 S2"
tags: ["lagoon", "2016"]
---

## Description

Gebrauchtboot; Baujahr 2016

## Specifications

- **Brand**: lagoon
- **Year**: 2016
- **Length**: 11.97 m
- **Beam**: 7.25 m
- **Boat type**: Katamaran
- **Engine**: 2 x 40 PS / 29 kW

PUT /api/listings/{id}

Aggiorna un annuncio. Aggiornamento parziale — solo i campi forniti vengono modificati. Auth richiesta — solo proprietario.

curl -X PUT https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW \
  -H "Authorization: Bearer own_aBcD123eFgH..." \
  -H "Content-Type: application/json" \
  -d '{ "price": { "amount": 280000, "currency": "EUR", "negotiable": false } }'

DELETE /api/listings/{id}

Soft-delete di un annuncio. Auth richiesta — solo proprietario.

curl -X DELETE https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW \
  -H "Authorization: Bearer own_aBcD123eFgH..."

# Response: { "deleted": true, "id": "lst_01KX..." }

PATCH /api/listings/{id}

Cambia lo stato di un annuncio. Auth richiesta — solo proprietario. Transizioni consentite: active, paused, sold.

curl -X PATCH https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW \
  -H "Authorization: Bearer own_aBcD123eFgH..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

POST /api/listings/{id}/publish

Pubblica un annuncio in bozza — lo sposta da bozza ad attivo. Auth richiesta — solo proprietario.

curl -X POST https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW/publish \
  -H "Authorization: Bearer own_aBcD123eFgH..."

POST /api/listings/{id}/contact

Invia un messaggio al proprietario dell'annuncio via email. Pubblico — nessuna auth richiesta. L'email del venditore non viene mai esposta. Rate limit: 5 all'ora per IP.

Corpo della richiesta

curl -X POST https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "Is this still available? Can you send more photos?"
  }'

# Response: { "message": "Your message has been sent to the listing owner." }

POST /api/listings/{id}/images

Carica immagini su un annuncio esistente (solo proprietario). Auth richiesta. Multipart form data, fino a 10 immagini per richiesta. Rate limit: 50 immagini al giorno.

curl -X POST https://api.owning.pro/api/listings/lagoon-400-s2-JP12QW/images \
  -H "Authorization: Bearer own_aBcD123eFgH..." \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg"

# Response: { "listing_id": "...", "slug": "...", "images": [...], "uploaded": 2 }

GET /api/listings.md

Ottieni il catalogo completo degli annunci come Markdown. Pubblico. Supporta gli stessi parametri query di GET /api/listings. Utile per agenti che vogliono sfogliare il catalogo in una singola richiesta.

curl "https://api.owning.pro/api/listings.md?category=boats&limit=5"

Categorie

GET /api/categories

Ottieni l'albero completo delle categorie con conteggi annunci. Pubblico. Gerarchico con count (annunci attivi) e children su ogni nodo.

Parametri query

curl https://api.owning.pro/api/categories

# Response:
{
  "categories": [
    {
      "id": "vehicles",
      "name": "Vehicles",
      "slug": "vehicles",
      "count": 7668,
      "children": [
        { "id": "boats", "name": "Boats", "slug": "boats", "count": 7668, "children": [] },
        { "id": "cars", "name": "Cars", "slug": "cars", "count": 0, "children": [] }
      ]
    }
  ]
}

GET /api/categories/{id}

Ottieni una singola categoria per ID o slug, con i figli diretti e i conteggi. Pubblico.

curl https://api.owning.pro/api/categories/boats

Tipi di asset

I tipi di asset definiscono template di attributi strutturati per categoria. Indicano quali campi sono disponibili per gli annunci in una data categoria e quali sono filtrabili nella ricerca.

GET /api/asset-types

Elenca tutti i template di tipi di asset disponibili. Pubblico.

GET /api/asset-types/{type}

Ottieni una definizione di tipo di asset specifica con tutti i suoi attributi. Pubblico. La risposta include quali attributi sono filtrabili e i loro tipi di filtro (range, select, boolean).

curl https://api.owning.pro/api/asset-types/boats

# Response:
{
  "id": "boats",
  "label": "Boats",
  "description": "Watercraft - sailboats, motorboats, catamarans, yachts",
  "categoryIds": ["boats"],
  "attributes": [
    { "key": "brand", "label": "Brand", "type": "string", "filterable": true, "filterType": "select" },
    { "key": "year", "label": "Year", "type": "number", "filterable": true, "filterType": "range" },
    { "key": "length", "label": "Length", "type": "number", "filterable": true, "filterType": "range", "unit": "m" },
    { "key": "boat_type", "label": "Boat Type", "type": "string", "filterable": true, "filterType": "select" }
  ]
}

Usa gli attributi filtrabili per costruire parametri query attr[...] per GET /api/listings.

Auth & API Keys

POST /api/auth/register

Registrati con email e password. Pubblico. Restituisce immediatamente un token di sessione JWT.

curl -X POST https://api.owning.pro/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepassword123","name":"Jane Doe"}'

# Response (201):
{
  "user": { "id": "usr_...", "email": "user@example.com", "name": "Jane Doe", "type": "human", "verified": false, "created_at": "..." },
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 604800
}

POST /api/auth/login

Accedi con email e password. Pubblico. Restituisce un JWT valido per 7 giorni.

curl -X POST https://api.owning.pro/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepassword123"}'

GET /api/me

Ottieni il profilo dell'utente autenticato. Auth richiesta.

curl https://api.owning.pro/api/me \
  -H "Authorization: Bearer own_aBcD123eFgH..."

# Response: { "user": { "id": "usr_...", "email": "...", "name": "...", "type": "human", ... } }

POST /api/api-keys

Genera una nuova API key. Auth richiesta (sessione JWT). La chiave in testo chiaro viene restituita una sola volta — conservala in modo sicuro.

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

# Response (201):
{
  "id": "apk_01JX...",
  "key": "own_aBcD123eFgH456iJkL789mNoP012qRsT345uVwX678yZ",
  "key_prefix": "own_aBcD1",
  "label": "My Integration Key",
  "permissions": "write",
  "created_at": "2026-07-10T12:00:00.000Z",
  "message": "Store this API key securely. It will not be shown again."
}

GET /api/api-keys

Elenca le API key dell'utente autenticato (senza testo chiaro). Auth richiesta.

curl https://api.owning.pro/api/api-keys \
  -H "Authorization: Bearer eyJhbG..."

# Response: { "keys": [{ "id": "apk_...", "key_prefix": "own_aBcD1", "label": "...", "permissions": "write", ... }] }

DELETE /api/api-keys/{id}

Revoca (soft-delete) una API key. Auth richiesta — solo il proprietario della chiave può revocare.

curl -X DELETE https://api.owning.pro/api/api-keys/apk_01JX... \
  -H "Authorization: Bearer eyJhbG..."

# Response: { "id": "apk_...", "revoked": true, "revoked_at": "..." }

Caricamento immagini

POST /api/upload

Carica un'immagine autonoma (nessun annuncio richiesto). Auth richiesta. L'immagine viene convertita in webp. Rate limit: 50 immagini al giorno. Usalo per ottenere URL di immagini prima di creare un annuncio.

curl -X POST https://api.owning.pro/api/upload \
  -H "Authorization: Bearer own_aBcD123eFgH..." \
  -F "file=@photo.jpg"

# Response (201):
{ "url": "https://static.owning.pro/images/tmp-usr01-abc/1.webp", "alt": "photo" }

Schema

GET /api/schema/listing

Ottieni lo JSON Schema (draft 2020-12) per il tipo di dato Listing. Pubblico. Usalo per validare i dati dell'annuncio prima di inviarli via POST /api/listings.

curl https://api.owning.pro/api/schema/listing

# Returns a JSON Schema document:
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://owning.pro/api/schema/listing",
  "title": "Owning Listing",
  "type": "object",
  "required": ["id", "slug", "title", "description", "category", ...],
  "properties": { ... }
}

GET /api/schema/listing.md

Ottieni lo schema degli annunci in formato Markdown per agenti IA. Pubblico.

curl https://api.owning.pro/api/schema/listing.md

Agent Discovery

GET /.well-known/ai.json

Descrizione leggibile da macchine della superficie API per l'auto-discovery degli agenti. Pubblico. Restituisce percorsi endpoint, schema di auth, rate limit, formati di risposta e riferimenti allo schema. Anch'esso scopribile tramite la direttiva AI-Discovery in /robots.txt.

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

# Response:
{
  "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",
      "docs": "/api/schema/listing.md"
    }
  },
  "formats": ["json", "markdown"]
}