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 से authenticate करें: Authorization: Bearer YOUR_API_KEY।
• Account के हिसाब से rate limits: प्रति मिनट 30 upserts और 120 reads।
• नई listings new-API quota में गिनी जाती हैं। Updates कभी नहीं गिनी जातीं।

Endpoints

उदाहरण

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

listing.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 लाइव होती है जब वह क्वालिटी रूल्स पास करती है और उसमें example response वाला कम से कम एक endpoint और active plans हों। इनके बिना, "publish": true पर 422 मिलता है। तैयार होते ही पब्लिश करने के लिए publish को छोड़ दें, या draft के रूप में रखने के लिए "publish": false भेजें। false किसी लाइव listing को कभी unpublish नहीं करता।

API fields. name नाम के नियमों का पालन करता है: अधिकतम 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 सेट होता है।