त्वरित शुरुआत
साइन इन करें, परीक्षण परियोजना बनाएँ, केवल आवश्यक स्कोप वाली कुंजी बनाएँ, GET /v1/tools कॉल करें, एक सेवा कॉन्फ़िगर करें और स्वीकृति परीक्षण के बाद अलग live कुंजी बनाएँ।
export GALON_API_BASE="https://api.galon.ai"
export GALON_API_KEY="gln_test_..."
curl "$GALON_API_BASE/v1/tools" -H "Authorization: Bearer $GALON_API_KEY"
प्रमाणीकरण और अलगाव
API कुंजी को Authorization: Bearer हेडर में भेजें। हर कुंजी एक tenant, परियोजना और वातावरण से बंधी है। इसे केवल सर्वर के सीक्रेट मैनेजर में रखें; ब्राउज़र, मोबाइल ऐप या स्रोत रिपॉज़िटरी में कभी नहीं।
सेवा तक सीमित कुंजियाँ
mail:send, domain:lookup या build:create जैसे सटीक स्कोप दें। हर ऐप के लिए अलग कुंजी रखें। जब तक सभी कार्रवाइयों की सच में आवश्यकता न हो, सेवा वाइल्डकार्ड से बचें और अनुपयोगी कुंजियाँ तुरंत रद्द करें।
mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read
असिंक्रोनस जॉब और आइडेम्पोटेंसी
परिवर्तन एक जॉब लौटाते हैं। स्थिर Idempotency-Key भेजें: समान कुंजी और आशय वही जॉब लौटाते हैं; अलग आशय के साथ वही कुंजी HTTP 409 देती है। जॉब एंडपॉइंट जाँचें और केवल सुरक्षित या आइडेम्पोटेंट अनुरोध दोहराएँ।
POST /v1/jobs
GET /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET /v1/builds/{job_id}/artifacts
ईमेल भेजना
POST /v1/emails में from_email, subject, text या html, और to दिया जाता है: एक पता या पतों की सूची। cc और bcc वैकल्पिक सूचियाँ हैं; to, cc और bcc मिलाकर अधिकतम 50 अलग-अलग प्राप्तकर्ता हो सकते हैं, और हर प्राप्तकर्ता आपके कोटा और बिल किए गए उपयोग में गिना जाता है। हर प्राप्तकर्ता को अपनी अलग प्रति और अपना एक-क्लिक सदस्यता-रद्द लिंक मिलता है, इसलिए bcc प्राप्तकर्ता कभी उजागर नहीं होते; दबाए गए प्राप्तकर्ता (बाउंस, शिकायतें, सदस्यता रद्द) छोड़ दिए जाते हैं। attachments अधिकतम 10 ऑब्जेक्ट की सूची है जिनमें filename, content (base64) और वैकल्पिक content_type होते हैं; एन्कोड किया गया संदेश 25 MB से कम होना चाहिए और निष्पादन योग्य फ़ाइलें अस्वीकार की जाती हैं। scheduled_at (समय क्षेत्र सहित ISO 8601, अधिकतम 72 घंटे पहले) भेजने को टालता है; कतार में रहते हुए POST /v1/emails/{job_id}/cancel उसे रद्द करता है। POST /v1/emails/batch में {"emails": [...]} के साथ बिना अटैचमेंट के 1 से 100 संदेश दिए जाते हैं; हर संदेश अपना अलग job बनता है, जो बैच की Idempotency-Key और अपनी स्थिति से idempotent होता है। एक प्राप्तकर्ता के लिए to_email अब भी स्वीकार है। केवल बैच पंजीकरण परमाणु है (atomic=true); निष्पादन और डिलीवरी स्वतंत्र हैं। पुनः प्रयास के लिए बिल्कुल वही क्रमबद्ध सूची आवश्यक है; सामग्री, आकार या क्रम में कोई भी बदलाव HTTP 409 लौटाता है।
POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel
त्रुटियाँ
HTTP 401 को अमान्य या समाप्त पहचान, 403 को अपर्याप्त स्कोप, 409 को आइडेम्पोटेंसी या संस्करण टकराव, 422 को अमान्य अनुरोध और 503 को अस्थायी अनुपलब्धता मानें।
मशीन-पठनीय संदर्भ
स्कीमा के लिए OpenAPI अनुबंध और एजेंट निर्देशों के लिए LLM एकीकरण गाइड का उपयोग करें। अंग्रेज़ी कैनोनिकल है; पथ, फ़ील्ड, स्कोप और उदाहरण हर अनुवाद में समान हैं।