API 참조

Owning.pro API는 클래스피드 등록글을 검색, 탐색, 생성, 관리하는 RESTful API입니다. 모든 엔드포인트는 JSON을 반환하며, 등록글 엔드포인트는 Markdown 응답도 지원합니다. API는 다음에서 사용 가능: https://api.owning.pro 그리고 다음에서 프록시됨: https://owning.pro/api.

엔드포인트 요약

* = 인증 필요(JWT 또는 API 키)

인증

공개 읽기 엔드포인트(GET)는 인증이 필요하지 않습니다. 쓰기 작업(POST, PUT, DELETE, PATCH)은 인증이 필요합니다.

docsApi.authDesc2

• JWT 세션 토큰 — POST /api/auth/register 또는 POST /api/auth/login으로 획득. 7일간 유효.
• API 키 — own_... 형식의 장수 키, POST /api/api-keys로 생성. 읽기, 쓰기, 관리 권한 지원.

API는 토큰 타입을 자동 감지: own_로 시작하는 토큰은 API 키로, 나머지는 JWT 세션으로 처리.

API 키 생성

# 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_limited의 error.code와 함께 429 Too Many Requests를 반환합니다.

응답 포맷

등록글 엔드포인트는 두 가지 응답 포맷을 지원합니다:

• JSON(기본값) — application/json. 구조화된 등록글 객체 반환.
• Markdown — text/markdown. YAML 프론트매터가 있는 기계 판독용 Markdown 문서 반환. URL에 .md를 추가하거나 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"

오류 포맷

모든 오류는 일관된 JSON 구조를 반환합니다:

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

등록글

GET /api/listings

페이지네이션, 정렬, 동적 속성 필터로 등록글 검색 및 필터링. 공개 — 인증 불필요.

쿼리 매개변수

응답 예제

{
  "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 }
}

예제: 필터로 검색

# 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"

상태 코드

POST /api/listings

docsApi.createListingDesc

요청 본문

예제

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"]
  }'

상태 코드

GET /api/listings/{id}

ID 또는 슬러그로 단일 등록글 가져오기. 공개. 상세 응답은 long_description(사용 가능한 경우)을 포함하며, 이는 목록 응답에 없습니다.

예제

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

기계 판독용 Markdown으로 등록글 가져오기. 공개. Markdown은 주요 메타데이터가 있는 YAML 프론트매터와 구조화된 섹션을 포함.

응답 예제

---
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}

등록글 업데이트. 부분 업데이트 — 제공된 필드만 변경. 인증 필요 — 소유자만.

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}

등록글 소프트 삭제. 인증 필요 — 소유자만.

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}

등록글 상태 변경. 인증 필요 — 소유자만. 허용된 전환: 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

임시 등록글 게시 — 임시에서 판매 중으로 이동. 인증 필요 — 소유자만.

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

POST /api/listings/{id}/contact

이메일로 등록글 소유자에게 메시지 전송. 공개 — 인증 불필요. 판매자의 이메일은 노출되지 않음. 속도 제한: IP당 시간당 5회.

요청 본문

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

기존 등록글에 이미지 업로드(소유자만). 인증 필요. 멀티파트 폼 데이터, 요청당 최대 10개 이미지. 속도 제한: 하루 50개 이미지.

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

전체 등록글 카탈로그를 Markdown으로 가져오기. 공개. GET /api/listings와 동일한 쿼리 매개변수 지원. 단일 요청으로 카탈로그를 탐색하려는 에이전트에 유용.

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

카테고리

GET /api/categories

등록글 수가 있는 전체 카테고리 트리 가져오기. 공개. 각 노드에 count(판매 중 등록글)와 children이 있는 계층 구조.

쿼리 매개변수

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}

ID 또는 슬러그로 단일 카테고리 가져오기, 직접 하위 카테고리와 수 포함. 공���.

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

자산 유형

자산 유형은 카테고리별 구조화된 속성 템플릿을 정의합니다. 해당 카테고리의 등록글에 사용 가능한 필드와 검색에서 필터 가능한 필드를 알려줍니다.

GET /api/asset-types

사용 가능한 모든 자산 유형 템플릿 나열. 공개.

GET /api/asset-types/{type}

모든 속성이 있는 특정 자산 유형 정의 가져오기. 공개. 응답은 필터 가능한 속성과 필터 타입(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" }
  ]
}

필터 가능한 속성을 사용하여 GET /api/listings의 attr[...] 쿼리 매개변수를 구성하세요.

인증 & API 키

POST /api/auth/register

이메일과 비밀번호로 가입. 공개. 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

이메일과 비밀번호로 로그인. 공개. 7일간 유효한 JWT 반환.

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

인증된 사용자의 프로필 가져오기. 인증 필요.

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

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

POST /api/api-keys

새 API 키 생성. 인증 필요(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 (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

인증된 사용자의 API 키 나열(평문 제외). 인증 필요.

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}

API 키 폐지(소프트 삭제). 인증 필요 — 키 소유자만 폐지 가능.

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

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

이미지 업로드

POST /api/upload

독립 이미지 업로드(등록글 불필요). 인증 필요. 이미지는 webp로 변환. 속도 제한: 하루 50개 이미지. 등록글 생성 전 이미지 URL을 가져오는 데 사용.

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" }

스키마

GET /api/schema/listing

Listing 데이터 타입의 JSON Schema(draft 2020-12) 가져오기. 공개. 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

AI 에이전트용 Markdown 형식의 등록글 스키마 가져오기. 공개.

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

에이전트 디스커버리

GET /.well-known/ai.json

에이전트 자동 디스커버리용 API 표면의 기계 판독용 설명. 공개. 엔드포인트 경로, 인증 방식, 속도 제한, 응답 포맷, 스키마 참조 반환. /robots.txt의 AI-Discovery 지시어로도 발견 가능.

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"]
}