# Listings API रेफरेंस

`PUT /api/listings` एक ही atomic कॉल में पूरी listing बनाता या अपडेट करता है: API, उसके endpoints, origin secret, plans, FAQs और linked APIs। या तो सब कुछ सेव होता है या कुछ नहीं। यही वह चीज़ है जो `provider_*` MCP tools अंदर से इस्तेमाल करते हैं, और आप इसे scripts या CI से सीधे कॉल कर सकते हैं।

## Access

- **verified email** वाला कोई भी account। Unverified या blocked accounts को `403` मिलता है।
- अपनी [API key](https://zylalabs.com/hi/docs/api-keys) से authenticate करें: `Authorization: Bearer YOUR_API_KEY`।
- Account के हिसाब से rate limits: प्रति मिनट 30 upserts और 120 reads।
- नई listings [new-API quota](https://zylalabs.com/hi/docs/quality-rules) में गिनी जाती हैं। Updates कभी नहीं गिनी जातीं।

## Endpoints

| Method | Path | उद्देश्य |
|---|---|---|
| PUT | `/api/listings` | एक listing बनाएं या अपडेट करें (या `"delete": true` से डिलीट करें) |
| GET | `/api/listings` | आपकी listings (`status`, `page`, `per_page`) |
| GET | `/api/listings/{product_key}` | एक listing की पूरी definition (origin secret कभी नहीं) |
| GET | `/api/listings/me` | आपका account, limits, valid plan नाम और parameter types |
| GET | `/api/listings/categories` | Category ids |

## उदाहरण

```bash
curl -X PUT https://zylalabs.com/api/listings \
  -H "Authorization: Bearer $ZYLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @listing.json
```

`listing.json`:

```json
{
  "product_key": "trustpilot-api",
  "publish": true,
  "api": {
    "name": "Trustpilot Reviews API",
    "short_description": "Retrieve Trustpilot company reviews, ratings and reviewer details in JSON.",
    "trial": false
  },
  "access": { "in": "header", "key": "X-Origin-Key", "value": "your-origin-secret" },
  "endpoints": [{
    "name": "Get Company Reviews",
    "description": "Returns the latest public reviews for a company domain with pagination.",
    "method": "GET",
    "base_url": "https://origin.example.com/v1/items/||domain||",
    "path_params": { "domain": "example.com" },
    "parameters": [
      { "key": "page", "type": "number", "description": "Page number, starting at 1.", "value": "1", "required": false }
    ],
    "headers": [{ "key": "Accept", "value": "application/json" }],
    "example_response": { "reviews": [{ "rating": 5 }] }
  }],
  "plans": [
    { "name": "Basic", "interval": "Monthly", "price": 24.99, "max_requests": 1000 },
    { "name": "Pro", "interval": "Monthly", "price": 49.99, "max_requests": 5000 },
    { "name": "ProPlus", "interval": "Monthly", "price": 99.99, "max_requests": 15000, "rate_limit": 120 }
  ],
  "faqs": [{ "question": "What data does it return?", "answer": "Public reviews with rating and text." }],
  "slaves": [{ "name": "Company Reviews Lookup API" }]
}
```

## नियम

**Identity.** `product_key` आपकी listing की अपनी स्थिर id है। एक नई key listing बनाती है; जो key आप पहले इस्तेमाल कर चुके हैं वह उसे अपडेट करती है। एक key उस account की होती है जिसने उसे बनाया (किसी और के लिए `403`)। डिलीट की गई listings एडिट्स स्वीकार नहीं करतीं (`409`)।

**Publishing.** listing लाइव होती है जब वह [क्वालिटी रूल्स](https://zylalabs.com/hi/docs/quality-rules) पास करती है और उसमें example response वाला कम से कम एक endpoint और active plans हों। इनके बिना, `"publish": true` पर `422` मिलता है। तैयार होते ही पब्लिश करने के लिए `publish` को छोड़ दें, या draft के रूप में रखने के लिए `"publish": false` भेजें। `false` किसी लाइव listing को कभी unpublish नहीं करता।

**API fields.** `name` [नाम के नियमों](https://zylalabs.com/hi/docs/quality-rules) का पालन करता है: अधिकतम 50 characters, इसमें "API" शब्द शामिल, हब पर unique। `short_description` कम से कम 50 characters। बाकी listing पेज Zyla आपके लिए पूरा करता है: long description आपकी short description से बनाई जाती है, और category और tags AI से चुने जाते हैं। अगर आप `long_description`, `category_id`, `tags` या `website_url` भेजते हैं, तो उन्हें नज़रअंदाज़ कर दिया जाता है और `warnings` में लिस्ट किया जाता है।

**Endpoints.** जब `endpoints` मौजूद हो तो वह पूरी लिस्ट होती है: endpoints method + `base_url` (query string के बिना) से मैच किए जाते हैं, नए बनाए जाते हैं और लिस्ट से गायब वाले डिलीट हो जाते हैं। endpoints को बिना बदले छोड़ने के लिए इसे छोड़ दें।
- Description कम से कम 40 characters। Method GET, POST, PUT, DELETE या PATCH।
- `base_url` एक valid URL होना चाहिए। Path parameters `||` के बीच जाते हैं, जैसे `/items/||domain||`, और `path_params` में एक example value के साथ।
- Parameters को `key`, `type` (string, number, email, url, domain, date, datetime) और कम से कम 10 characters का description चाहिए।
- `example_response` ज़रूरी है, अधिकतम 10,000 characters।

**Origin secret (`access`).** एक header या query parameter जो Zyla आपके origin पर हर कॉल में जोड़ता है, ताकि आपका server केवल हब से आने वाला traffic स्वीकार करे। यह hidden रूप से स्टोर होता है और कभी लौटाया या लॉग नहीं किया जाता। मौजूदा वाले को रखने के लिए इसे छोड़ दें; हटाने के लिए `null` भेजें।

**Plans.** सटीक नाम: Free, Basic, Pro, ProPlus, Premium, Elite, Ultimate, Pay as you go। `price` USD में; yearly plans अपनी final yearly price रखते हैं। `max_requests` प्रति साइकिल; एक सस्ते plan में उसी interval के ज़्यादा महंगे plan से कम requests होनी चाहिए। `rate_limit` 60 से 240 प्रति मिनट तक। कम से कम तीन paid monthly plans active रहनी चाहिए। अगर आप नई listing पर कोई plans नहीं भेजते, तो एक default सेट बना दिया जाता है।

**FAQs.** मौजूद होने पर पूरी लिस्ट, अधिकतम 10। Question 5–100 characters, answer 3–700।

**Linked APIs (`slaves`).** आपकी API के variants जिनका अपना नाम और पेज होता है और जो इसके endpoints फिर से इस्तेमाल करते हैं। वे नाम से मैच किए जाते हैं और master के endpoints में हुए बदलावों को फॉलो करते हैं। Master के पास endpoints होने चाहिए, और एक linked API के अपने linked APIs नहीं हो सकते।

**Delete.** `{"product_key": "...", "delete": true}` listing को डिलीट करता है। जब तक उसके paid subscriptions हैं, यह `409` के साथ अस्वीकार होता है। Linked APIs केवल तब डिलीट होते हैं जब आप उन्हें `slaves` में नाम से बताते हैं।

**Not supported.** Response transformations, request bodies और file uploads (`422 not_supported`)। इनके लिए web wizard इस्तेमाल करें।

## Responses

Success: `{"success": true, "listing": {...}, "warnings": []}`, create पर `201` और update पर `200`। listing लाइव होने पर `listing.url` सेट होता है।

| Status | `code` | मतलब |
|---|---|---|
| 401 | `unauthenticated` | Key गायब या अमान्य |
| 403 | `forbidden` | Unverified या blocked account, या `product_key` किसी दूसरे account का है |
| 404 | `not_found` | अनजान `product_key` |
| 409 | `name_taken`, `active_subscriptions`, `endpoints_required`, `listing_deleted`, `slave_of_slave`, `product_key_conflict` | Conflict; कुछ नहीं बदला |
| 422 | `validation_failed`, `ai_validation_failed`, `not_supported` | field के हिसाब से `errors`, जैसे `endpoints.2.parameters.0.description` |
| 429 | `creation_limit_reached` | New-API quota खत्म; `retry_after` सेकंड और एक `Retry-After` header |
| 503 | `ai_unavailable` | Content check ने जवाब नहीं दिया; कुछ भी सेव नहीं हुआ; फिर से कोशिश करें |
| 500 | `server_error` | अप्रत्याशित failure; कुछ भी सेव नहीं हुआ |


---
Source: https://zylalabs.com/hi/docs/listings-api