দ্রুত শুরু
সাইন ইন করুন, একটি টেস্ট প্রকল্প তৈরি করুন, শুধু প্রয়োজনীয় scope দিয়ে কী তৈরি করুন, 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"
প্রমাণীকরণ ও বিচ্ছিন্নতা
Authorization: Bearer হেডারে API কী পাঠান। প্রতিটি কী একটি tenant, প্রকল্প ও পরিবেশের সঙ্গে যুক্ত। এটি শুধু সার্ভার-সাইড সিক্রেট ম্যানেজারে রাখুন; ব্রাউজার, মোবাইল অ্যাপ বা সোর্স রিপোজিটরিতে কখনও নয়।
পরিষেবা-সীমিত কী
mail:send, domain:lookup বা build:create-এর মতো নির্দিষ্ট scope দিন। প্রতিটি অ্যাপের জন্য একটি কী ব্যবহার করুন। সত্যিই সব অপারেশন দরকার না হলে service wildcard এড়িয়ে চলুন এবং অব্যবহৃত কী সঙ্গে সঙ্গে প্রত্যাহার করুন।
mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read
অ্যাসিঙ্ক্রোনাস job ও idempotency
পরিবর্তন একটি job ফেরত দেয়। স্থির Idempotency-Key পাঠান: একই কী ও উদ্দেশ্য একই job ফেরত দেয়; একই কী ভিন্ন উদ্দেশ্যে HTTP 409 দেয়। job endpoint পরীক্ষা করুন এবং শুধু নিরাপদ বা idempotent অনুরোধ পুনরায় চেষ্টা করুন।
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 অপর্যাপ্ত scope, 409 idempotency বা version দ্বন্দ্ব, 422 অবৈধ অনুরোধ এবং 503 সাময়িক অনুপলব্ধতা।
মেশিন-পঠনযোগ্য রেফারেন্স
schema-এর জন্য OpenAPI contract এবং agent নির্দেশনার জন্য LLM integration guide ব্যবহার করুন। ইংরেজি canonical; path, field, scope ও উদাহরণ প্রতিটি অনুবাদে একই।