{"openapi":"3.1.0","info":{"title":"IconIL API","version":"1.0.0","summary":"חיפוש ואחזור של אייקונים, כולל חיפוש בעברית.","description":"ה-API הציבורי של IconIL. קריאה בלבד, ללא מפתח, עם הגבלת קצב לפי כתובת. החיפוש מבין עברית (`lang=he`): מילים בעברית מומרות למושגים באנגלית. מזהי האייקונים הם באנגלית בכל מקרה. הרישיון של כל אייקון הוא של הסט שלו, ראו `NOTICE.md`.","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"/","description":"השרת הנוכחי"}],"security":[{},{"bearerKey":[]}],"tags":[{"name":"חיפוש","description":"מציאת אייקונים."},{"name":"אחזור","description":"קבלת אייקון בודד או כמה אייקונים."},{"name":"אוספים","description":"סטים של אייקונים."}],"paths":{"/api/v1/search":{"get":{"operationId":"searchIcons","tags":["חיפוש"],"summary":"חיפוש אייקונים","description":"מחזיר אייקונים לפי שאילתה. שאילתה בעברית מורחבת למושגים באנגלית, ובתשובה מופיע `matchedConcepts` שמסביר מה הובן, ו-`unknownTerms` עם מילים שלא זוהו.","parameters":[{"name":"q","in":"query","required":true,"description":"השאילתה, בעברית או באנגלית.","schema":{"type":"string"},"example":"בית"},{"name":"collection","in":"query","description":"הגבלה לסט אחד, למשל `lucide`.","schema":{"type":"string"}},{"name":"style","in":"query","description":"סגנון: `outline`, `solid` או מזהה סגנון מדויק.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"מספר התוצאות המרבי (עד 999, ברירת מחדל 32).","schema":{"type":"integer","minimum":1,"maximum":999,"default":32}},{"name":"svg","in":"query","description":"`1` כדי לכלול את ה-SVG בכל תוצאה.","schema":{"type":"string","enum":["1"]}},{"name":"prefer","in":"query","description":"סט מועדף לסידור התוצאות.","schema":{"type":"string"}},{"name":"lang","in":"query","description":"`he` או `auto` מרחיבים שאילתה עברית; `en` מחפש את הטקסט כפי שהוקלד.","schema":{"type":"string","enum":["he","en","auto"],"default":"auto"}}],"responses":{"200":{"description":"תוצאות החיפוש.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"description":"חסר `q`, או שם סט לא מוכר.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/icon":{"get":{"operationId":"getIcon","tags":["אחזור"],"summary":"אייקון בודד","description":"מחזיר אייקון כ-JSON, או כקוד מוכן לפי `format`.","parameters":[{"name":"id","in":"query","required":true,"description":"מזהה אייקון בצורה `סט:שם`, למשל `lucide:house`.","schema":{"type":"string"},"example":"lucide:house"},{"name":"format","in":"query","description":"`json` (ברירת מחדל) מחזיר אובייקט; שאר הערכים מחזירים טקסט: `svg`, `html`, `react`, `react-native`, `vue`, `svelte`, `solid`, `flutter`, `jsx`.","schema":{"type":"string","enum":["json","svg","react","react-native","vue","svelte","solid","flutter","jsx","html"],"default":"json"}},{"name":"color","in":"query","description":"צבע, למשל `#1e40af`. ברירת המחדל היא `currentColor`.","schema":{"type":"string"}},{"name":"variant","in":"query","description":"מזהה סגנון בתוך הסט.","schema":{"type":"string"}},{"name":"size","in":"query","description":"גודל בפיקסלים.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"האייקון. הסוג תלוי ב-`format`.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IconRecord"}},"image/svg+xml":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"חסר `id`, או `format` לא מוכר.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"האייקון לא נמצא.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/icons":{"get":{"operationId":"getIcons","tags":["אחזור"],"summary":"כמה אייקונים בבקשה אחת","description":"עד 20 מזהים. אפשר גם בגוף בקשה (POST) כשהרשימה ארוכה.","parameters":[{"name":"ids","in":"query","required":true,"description":"מזהים מופרדים בפסיקים.","schema":{"type":"string"},"example":"lucide:house,lucide:user"},{"name":"color","in":"query","schema":{"type":"string"}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"האייקונים שנמצאו, ושגיאות לכל מזהה שלא נמצא.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IconsBatch"}}}},"400":{"description":"לא נשלחו מזהים.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"getIconsPost","tags":["אחזור"],"summary":"כמה אייקונים בבקשה אחת (גוף JSON)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":20},"color":{"type":"string"}},"required":["ids"]}}}},"responses":{"200":{"description":"האייקונים שנמצאו, ושגיאות לכל מזהה שלא נמצא.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IconsBatch"}}}},"400":{"description":"לא נשלחו מזהים.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/collections":{"get":{"operationId":"listCollections","tags":["אוספים"],"summary":"רשימת הסטים","parameters":[{"name":"search","in":"query","description":"סינון לפי מזהה או שם.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"מספר התוצאות המרבי (עד 500, ברירת מחדל 80).","schema":{"type":"integer","minimum":1,"maximum":500,"default":80}}],"responses":{"200":{"description":"הסטים, מהגדול לקטן.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collections"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/similar":{"get":{"operationId":"similarIcons","tags":["חיפוש"],"summary":"אייקונים דומים","parameters":[{"name":"id","in":"query","required":true,"description":"מזהה אייקון בצורה `סט:שם`, למשל `lucide:house`.","schema":{"type":"string"},"example":"lucide:house"},{"name":"limit","in":"query","description":"מספר התוצאות המרבי (עד 100, ברירת מחדל 10).","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"אייקונים עם שם זהה או קרוב בסטים אחרים.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Similar"}}}},"400":{"description":"חסר `id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/equivalent":{"get":{"operationId":"equivalentIcon","tags":["חיפוש"],"summary":"האייקון המקביל בסט אחר","parameters":[{"name":"id","in":"query","required":true,"description":"מזהה אייקון בצורה `סט:שם`, למשל `lucide:house`.","schema":{"type":"string"},"example":"lucide:house"},{"name":"to","in":"query","required":true,"description":"הסט היעד.","schema":{"type":"string"},"example":"tabler"}],"responses":{"200":{"description":"האייקון המקביל.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Equivalent"}}}},"400":{"description":"חסר `id` או `to`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"אין אייקון מקביל בסט היעד.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"חרגתם ממכסת הבקשות. חכו את מספר השניות שב-`Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"500":{"description":"שגיאה בשרת.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"מפתח API אופציונלי: מעלה את מכסת הבקשות. אפשר גם בכותרת `X-API-Key`."}},"headers":{"XRateLimitLimit":{"description":"מספר הבקשות המרבי בחלון.","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"כמה בקשות נותרו בחלון הנוכחי.","schema":{"type":"integer"}},"XRateLimitReset":{"description":"שניות עד סוף החלון.","schema":{"type":"integer"}},"RetryAfter":{"description":"שניות להמתנה לפני ניסיון נוסף.","schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"RateLimited":{"type":"object","properties":{"error":{"const":"rate_limited"},"message":{"type":"string"},"retryAfterSeconds":{"type":"integer"}},"required":["error","retryAfterSeconds"]},"IconHit":{"type":"object","properties":{"id":{"type":"string","description":"`סט:שם`"},"legacyId":{"type":"string"},"set":{"type":"string"},"name":{"type":"string"},"styles":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"score":{"type":"number"},"svg":{"type":"string"}},"required":["id","legacyId","set","name","styles","score"]},"IconRecord":{"type":"object","properties":{"id":{"type":"string"},"legacyId":{"type":"string"},"set":{"type":"string"},"name":{"type":"string"},"styleId":{"type":"string"},"svg":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}},"required":["id","legacyId","set","name","styleId","svg"]},"MatchedConcept":{"type":"object","properties":{"term":{"type":"string","description":"המילה בעברית כפי שהוקלדה."},"concepts":{"type":"array","items":{"type":"string"}},"match":{"type":"string","enum":["exact","prefix","variant","latin"]}},"required":["term","concepts","match"]},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"icons":{"type":"array","items":{"$ref":"#/components/schemas/IconHit"}},"lang":{"const":"he"},"matchedConcepts":{"type":"array","items":{"$ref":"#/components/schemas/MatchedConcept"}},"unknownTerms":{"type":"array","items":{"type":"string"},"description":"מילים בעברית שלא נמצאו במילון."}},"required":["query","total","icons"]},"IconsBatch":{"type":"object","properties":{"icons":{"type":"array","items":{"$ref":"#/components/schemas/IconRecord"}},"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"string"}},"required":["id","error"]}}},"required":["icons","errors"]},"Collections":{"type":"object","properties":{"total":{"type":"integer"},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":["string","null"]},"label":{"type":"string"},"homepage":{"type":["string","null"]},"count":{"type":"integer"},"styles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"group":{"type":"string"}}}}},"required":["id","label","count"]}}},"required":["total","collections"]},"Similar":{"type":"object","properties":{"iconId":{"type":"string"},"icons":{"type":"array","items":{"$ref":"#/components/schemas/IconHit"}}},"required":["iconId","icons"]},"Equivalent":{"type":"object","properties":{"from":{"type":"string"},"to":{"$ref":"#/components/schemas/IconHit"}},"required":["from","to"]}}}}