REST API

წაიკითხეთ და ჩაწერეთ თქვენი მონიტორები, წაიკითხეთ და განაახლეთ ინციდენტები და ატვირთეთ source map-ები. ყველაფერი აქ იმავე უფლებების შემოწმებასა და კლიენტების იმავე გამიჯვნის ფილტრს იყენებს, რასაც პანელი — API-ის მხარეს ცალკე რეალიზაცია, რომელიც მისგან დაშორდებოდა, არ არსებობს.

შედის ყველა გეგმაში, უფასოს ჩათვლით. არაფრის დამატებით ყიდვა არ სჭირდება და არ არსებობს საფეხური, რომელიც ამას ხსნის.

საბაზისო URL

https://vitrinaengine.com/api/v1

მანქანურად წასაკითხი აღწერა

/openapi.json არის OpenAPI 3.1 დოკუმენტი, რომელიც ფარავს ამ გვერდის ყველა მარშრუტს. მიუთითეთ მასზე კლიენტის გენერატორი, ან გადაეცით აგენტს, რომელსაც ამ API-სთან მუშაობა სჭირდება ახსნის გარეშე.

ის გენერირდება თავად სერვისიდან და არ იწერება მის გვერდით: მარშრუტები მოდის იმ ზედაპირიდან, რომელსაც API თავად აქვეყნებს GET /-ზე, სტრუქტურები და მათი განმარტებები — იმავე .proto ფაილებიდან მისამართზე /api/proto, ხოლო სიხშირის ლიმიტები — იმ კოდიდან, რომელიც მათ ამოქმედებს. ბილდი ვარდება, როცა დოკუმენტი და API დაშორდება — ამიტომ ის აღწერს იმას, რაც რეალურად ბრუნდება და არა იმას, რაც ბოლო რედაქტირებისას იყო სწორი.

ის აღწერს სტრუქტურებს. მიზეზები ამ გვერდზეა — რომ სხვა ორგანიზაციის id პასუხობს 404-ს, რომ config არასდროს ბრუნდება — და მათ ვერც ერთი გენერატორი ვერ დაწერს.

აგენტებისთვის: MCP

https://vitrinaengine.com/mcp არის Model Context Protocol სერვერი. დაამატეთ ის MCP კლიენტს API-გასაღებით, როგორც bearer-ტოკენით, და აგენტი შეძლებს წაიკითხოს თქვენი მონიტორები, ინციდენტები, შეცდომები და ანალიტიკა — და შექმნას, შეცვალოს და წაშალოს მონიტორები — ისე, რომ API-ის მუშაობის ახსნა არ დასჭირდეს.

{
  "mcpServers": {
    "vitrina-engine": {
      "type": "http",
      "url": "https://vitrinaengine.com/mcp",
      "headers": { "Authorization": "Bearer vte_your_key_here" }
    }
  }
}

ის ყველაფერს კითხულობს და სამ რამეს წერს. ამ გვერდის ყოველი GET ოპერაცია ინსტრუმენტია, ასევე POST /monitors, PATCH /monitors/{id} და DELETE /monitors/{id}. სხვა ჩამწერი არაფერი მისაწვდომი არაა — არც სამუშაო სივრცე, არც წევრი, არც API-გასაღები, არც სტატუსის გვერდი და არც თქვენი ანგარიში — რადგან მათთვის ინსტრუმენტი არ არსებობს, დაშვებული ჩაწერების სია კი სამი სტრიქონია, რომელსაც ვიღაცამ განზრახ უნდა დაუმატოს.

ჩაწერის უფლების არმქონე გასაღები კვლავ უარყოფილია. ინსტრუმენტის გამოძახება იგივე მოთხოვნაა, რასაც გასაღები პირდაპირ გააგზავნიდა — იმავე უფლებების შემოწმებით და იმავე მოიჯარის ფილტრით: მხოლოდ კითხვის გასაღების მქონე აგენტი კითხულობს. მიეცით სწორედ ასეთი, თუ არ გინდათ, რომ თქვენი მონიტორინგი შეცვალოს — და ელოდეთ, რომ კლიენტი წაშლამდე გკითხავთ: მონიტორთან ერთად მისი ისტორიაც ქრება და უკან დაბრუნება არ არის. იმისთვის, რომ მონიტორი გაჩუმდეს და არ დაიკარგოს, დააპაუზეთ PATCH-ით.

რაკი იგივე მოთხოვნაა, ის ზუსტად იმას ხედავს, რასაც გასაღები, წერს იმავე აუდიტის ჩანაწერს, რასაც დაფა დაწერდა, და იმავე სიხშირის ლიმიტს ხარჯავს — ორჯერ: ერთხელ გამოძახებაზე და ერთხელ მის შიგნით მოთხოვნაზე. ჩაწერა ჩაწერის ლიმიტს ხარჯავს.

ერთი რამ იცოდეთ, სანამ აგენტი მონიტორს შეასწორებს: config მთლიანად იცვლება და არ ერწყმის ძველს. ჯერ წაიკითხეთ მონიტორი, შეცვალეთ საჭირო ველი და მთელი ობიექტი დააბრუნეთ. ნაწილობრივი კონფიგურაცია ჩუმად აგდებს იმ ჰედერებსა და ავტორიზაციის მონაცემებს, რომლებზეც შემოწმებაა დამოკიდებული — და მუშაობას განაგრძობინებს.

ავთენტიფიკაცია

შექმენით გასაღები განყოფილებაში პარამეტრები → API-გასაღებები და გაგზავნეთ bearer-ტოკენად. გასაღები ერთხელ, შექმნისას ჩანს, და მხოლოდ ჰეშის სახით ინახება — თუ დაკარგავთ, ახალი შექმენით.

curl https://vitrinaengine.com/api/v1/summary \
  -H "Authorization: Bearer vte_your_key_here"

გასაღები არასდროს იძლევა იმაზე მეტს, ვიდრე მისი შემქმნელი ფლობდა. ის იმ ადამიანის წევრობაზეა მიბმული და ამიტომ მის როლს ატარებს: გასაღები, რომელიც მხოლოდ კითხვის როლის მქონემ შექმნა, ვერ ჩაწერს, რაც არ უნდა გააგზავნოთ. გასაღები ასევე შეიძლება ერთი სამუშაო სივრცით შემოიფარგლოს — მაშინ ყოველი პასუხი მასზე იფილტრება, ხოლო მის გარეთ არსებული ამ გასაღებისთვის არ არსებობს.

ორგანიზაციიდან ადამიანის წაშლა იმავე ოპერაციაში აუქმებს მის მიერ შექმნილ გასაღებებს. წვდომის ჩამორთმევამ სააუთენტიფიკაციო მონაცემებიც უნდა წაიღოს, თორემ ადამიანს მოქმედი რჩება.

შეთანხმებები

ყოველი წარმატებული პასუხი არის JSON-ობიექტი თვისებით data. ყოველი წარუმატებელი — JSON-ობიექტი თვისებით error, რომელიც ადამიანისთვის განკუთვნილ ფრაზას შეიცავს.

{ "data": { "id": "8f14e45f-…", "name": "Marketing site" } }

{ "error": "This key cannot create monitors." }

პასუხები იგზავნება Cache-Control: private, no-store-ით. ეს გასაღებზე მიბმული მონაცემებია საერთო წყაროზე და არცერთმა პროქსიმ არ უნდა შეინახოს.

Protobuf და gzip

/api/v1-ის ქვეშ ყველა ბოლოწერტილი Protocol Buffers-საც ემსახურება. Accept: application/x-protobuf-ით პასუხი protobuf-ში მოდის; თუ protobuf-ის body-ს Content-Type: application/x-protobuf-ით გაგზავნით, პასუხიც იმავე ფორმატში დაბრუნდება. არცერთის გარეშე ეს JSON-ია, ზუსტად ისე, როგორც ადრე.

curl https://vitrinaengine.com/api/v1/monitors \
  -H "Authorization: Bearer vte_your_key_here" \
  -H "Accept: application/x-protobuf" \
  --compressed -o monitors.pb

შეტყობინებები გამოქვეყნებულია: /api/proto ყველა ფაილს ჩამოთვლის. ჩამოტვირთეთ ისინი მათივე ბილიკების შენარჩუნებით და protoc -I ამ საქაღალდეზე მიუთითეთ. სამი რამ განსხვავდება იმისგან, რასაც protobuf-ისგან მოელით: ველი, რომელიც შეიძლება ცარიელი იყოს, JSON-ში null-ია, protobuf-ში კი საერთოდ არ არის; რამდენიმე ველი, რომლის ფორმაც იცვლება — მაგალითად, მონიტორის ან არხის config — სტრიქონში მოთავსებული JSON-დოკუმენტია; ხოლო StringList ფუთავს სიას, რომელიც თავად შეიძლება null იყოს.

Gzip ორივე მიმართულებით მუშაობს: Accept-Encoding: gzip პასუხებისთვის, Content-Encoding: gzip მოთხოვნებისთვის. რადგან ერთი და იმავე URL-იდან ორ კლიენტს ახლა სხვადასხვა ბაიტები შეიძლება მიუვიდეს, ყველა პასუხს ახლავს Vary: Accept, Content-Type.

სტატუსის კოდები

უარის კოდები

ყოველი არა-2xx პასუხი წინადადების გვერდით ატარებს code-ს — not_found, limit_reached, rate_limited — და სწორედ ეს ველია, რომელზეც უნდა დაეყრდნოთ. error-ის ტექსტი ჟურნალის მკითხველისთვის დაწერილი პროზაა და ნებისმიერ დროს შეიძლება გადაიწეროს; კოდი კი მდგრადია. სადაც წინადადება მნიშვნელობას ასახელებს, vars ატარებს მათ ტექსტად, რომ თქვენს ენაში იქ დასვათ, სადაც გრამატიკა მოითხოვს, და არა ინგლისურიდან ამოიღოთ.

{
  "error": "The Pro plan includes 50 monitors, and you have 50.",
  "code": "limit_reached",
  "vars": { "plan": "pro", "limit": "50", "current": "50", "resource": "monitors" }
}

სწორედ აქედან ხატავენ ჩვენი აპლიკაციები უარს მკითხველის ენაზე. თქვენთვის უცნობ კოდს იგივენაირად მოექეცით — დაუბრუნდით error-ს — რადგან ახალი კოდები ვერსიის შეცვლის გარეშე ემატება.

სიხშირის ლიმიტები

ორგანიზაციაზე და არა გასაღებზე — კიდევ ერთი გასაღების შექმნა მათ არ ზრდის.

ლიმიტს ზემოთ ბრუნდება 429 სათაურით Retry-After, სადაც მითითებულია მთელი წამები ფანჯრის განულებამდე. დაიცავით ის და მაშინვე ხელახლა ნუ სცდით.

ისინი იქაა დაყენებული, სადამდეც ჩვეულებრივი ინტეგრაცია არ აღწევს: კედლის დაფა, რომელიც ათ წამში ერთხელ ითხოვს, 120 კითხვიდან ექვსს ხარჯავს. ყველა გეგმაზე ისინი ერთნაირია, რადგან კოლექციური ბოლოწერტილები ყველაფერს ერთი პასუხით აბრუნებს — ხუთასმონიტორიან ანგარიშს ოცმონიტორიანზე მეტი მოთხოვნა არ სჭირდება. source map-ებს საათობრივი კვოტა აქვს, რადგან ისინი განთავსების დროს ერთბაშად მოდის, სადაც ფრონტენდს ადვილად ასი ფრაგმენტი აქვს.

404 და არა 403, განზრახ

სხვა კლიენტს კუთვნილ იდენტიფიკატორზე პასუხად ბრუნდება „Not found.“, და არა „Forbidden.“ პასუხი 403 დაადასტურებდა, რომ ჩანაწერი არსებობს, და ბოლოწერტილს გადააქცევდა საშუალებად, შემოწმდეს, ნამდვილია თუ არა იდენტიფიკატორი. ნუ წაიკითხავთ 404-ს როგორც მტკიცებულებას იმისა, რომ არსად არაფერია — მხოლოდ იმისა, რომ არაფერია ისეთი, რის ნახვის უფლებაც ამ გასაღებს აქვს.

ბოლოწერტილები

GET /search

ყველაფერი ანგარიშში, რაც ?q=-ს ემთხვევა: მონიტორები, ინციდენტები და მათი ანალიზები, სერვერები, სტატუსის გვერდები, სამუშაო სივრცეები, შეტყობინების არხები, ტექმომსახურების ფანჯრები, შეცდომების პროექტები და პრობლემები, ანალიტიკის საიტები, წევრები და მოწვევები, API გასაღებები, აგენტები და პირადი ზონდები. ერთი მოთხოვნა თითოეული ტიპისთვის ცალკე მოთხოვნის ნაცვლად.

?type= ზღუდავს ტიპებს მძიმით გამოყოფილი სიით, ხოლო ?limit= ზღუდავს თითოეული ტიპის შედეგებს 1-დან 20-მდე (ნაგულისხმევი 5). თითოეული ტიპი მოითხოვს იმავე უფლებას, რასაც მისი საკუთარი ენდპოინტი; ტიპი, რომლის წაკითხვაც თქვენს გასაღებს არ შეუძლია, არ ჩანს ისევე, როგორც ტიპი შედეგების გარეშე. არაფერი დაშიფრული, ჰეშირებული ან საიდუმლო არ იძებნება და არ ბრუნდება.

GET /summary

მთვლელები, კედლის დაფისთვის ან დღიური შეჯამებისთვის. საჭიროებს monitor:read-ს.

{
  "data": {
    "total": 42, "up": 39, "degraded": 1, "down": 1,
    "paused": 1, "pending": 0,
    "openIncidents": 2, "suppressedIncidents": 1
  }
}

suppressedIncidents ითვლის ინციდენტებს, რომლებიც შეჩერებულია იმიტომ, რომ სხვის გავრცელების არეალში ხვდება. ისინი ნამდვილია და ცალკე შეფერხებები არაა.

GET /setup

რა რჩება ახალ ანგარიშს გასაკეთებელი — იგივე ოთხი კითხვა, რომელსაც პანელის დაწყების სია სვამს, ყოველ წაკითხვაზე თავიდან გამოთვლილი. საჭიროებს monitor:read-ს.

{
  "data": {
    "hasMonitor": true,
    "hasConfirmedChannel": false,
    "hasStatusPage": false,
    "hasColleague": false,
    "dismissedAt": null
  }
}

hasConfirmedChannel კითხულობს, შეძლებდა თუ არა შეტყობინება მართლა მისვლას, და არა იმას, არსებობს თუ არა არხი. ეს ორი ერთხელ ცუდად დაშორდა ერთმანეთს, და სია, რომელიც შეტყობინებებს მოწყობილად ჩათვლიდა ისეთი არხისთვის, რომელზეც გაგზავნაზე უარს ვამბობთ, იმავე შეცდომას გაიმეორებდა დამამშვიდებელი სახით.

hasColleague ითვლის წევრობებს და არასოდეს მოწვევებს: გაგზავნილმა და მიუღებელმა მოწვევამ არავინ დაამატა.

/summary-ში არაა ჩაკეცილი, რადგან ის წერტილი მხოლოდ სტატუსების დათვლაა და სხვა არაფერი: კედლის დაფას, რომელიც მას ყოველ რამდენიმე წამში ეკითხება, არ სჭირდება ხუთი დამატებითი მოთხოვნა იმ შეხსენების დასახატად, რომელიც იმას მიემართება, ვინც ანგარიში თვეების წინ მოაწყო.

DELETE /setup

გამოტოვებს სიას. საჭიროებს org:update-ს, რადგან მისი დამალვა ორგანიზაციის მასშტაბის ერთი ჩანაწერია და არა თითოეული ადამიანის პარამეტრი: ვინც შემდეგ მოვა, მას ხელახლა აღარ ეჩვენება.

ანგარიშში სხვა არაფერი იცვლება და აუდიტის ჩანაწერი არ იწერება: შეხსენების დამალვა არაფერს ცვლის იმაში, როგორ იქცევა პროდუქტი, როგორ აფრთხილებს ან როგორ ითვლის ანგარიშს.

GET /monitors

ყველა მონიტორი, რომელსაც გასაღები ხედავს. საჭიროებს monitor:read-ს. თითოეული ატარებს id, name, kind, status, statusSince, enabled, intervalSeconds, tags, workspace, lastCheckedAt, lastResponseTimeMs, lastMessage, uptime24h, uptime30d და openIncidentId.

?tag=prod,eu ავიწროებს სიას იმ მონიტორებამდე, რომლებიც ატარებენ ყველა დასახელებულ ჭდეს — და, და არა ან: მეორე ჭდის დასახელება ყოველთვის ნაკლებ მონიტორს აბრუნებს და არა მეტს. დაფის საკუთარი ფილტრი იმავენაირად იკითხება. ჭდეები ინახება პატარა ასოებით და აქ მნიშვნელობაც იმავენაირად გარდაიქმნება შედარებამდე, ამიტომ ?tag=Prod მათ პოულობს. ჩანაწერი, რომელიც ჭდე ვერ იქნებოდა — ცარიელი ან ჭდისთვის დასაშვებზე გრძელი — უგულებელყოფილია და ფილტრის დანარჩენი ნაწილი მაინც მოქმედებს, ნაცვლად მოთხოვნის უარყოფისა: ბმულმა მუშაობა არ უნდა შეწყვიტოს იმიტომ, რომ მისი ერთ-ერთი ჭდე გადაერქვა.

config არასდროს ბრუნდება. ზოგი სახისთვის ის მოთხოვნის სათაურებსა და სააუთენტიფიკაციო მონაცემებს შეიცავს, და მხოლოდ კითხვის უფლების მქონე გასაღები არ უნდა იყოს გზა იმ საიდუმლოების უკან წასაკითხად, რომლებიც ვიღაცამ ფორმაში აკრიფა.

POST /monitors

საჭიროებს monitor:create-ს. სავალდებულოა name, kind, workspaceId და config. არასავალდებულო: intervalSeconds (ნაგულისხმევად 300), confirmations, dependsOn.

curl -X POST https://vitrinaengine.com/api/v1/monitors \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site",
    "kind": "http",
    "workspaceId": "…",
    "intervalSeconds": 60,
    "config": {
      "url": "https://example.com",
      "assertions": [{ "type": "status_code", "operator": "lt", "value": "400" }]
    }
  }'

პასუხობს 201-ით ახალი იდენტიფიკატორით. ინტერვალი თქვენი გეგმის ქვედა ზღვრამდე აიწევს და არ უარიყოფა: 10 წამის მოთხოვნა გეგმაზე, სადაც ქვედა ზღვარი 60-ია, 60-ს მოგცემთ — უკან წაიკითხეთ, თუ ეს მნიშვნელოვანია.

GET /monitors/{id}

ერთი მონიტორი, ყველაფრით, რასაც სია იძლევა, პლუს paused. საჭიროებს monitor:read-ს.

mail_posture-ის, tls_audit-ისა და snmp-ისთვის ის ასევე ატარებს lastCheckDetail-ს, ბოლო შემოწმების საკუთარ შედეგს: დასკვნებს სტატუსის უკან, თითოეულს სტაბილური code-ითა და severity-თ, პლუს TLS-შეფასებას ან SNMP-ჩვენებებს. პირველ შემოწმებამდე ის null-ია, დანარჩენ ყველა სახეში კი საერთოდ არ არის.

PATCH /monitors/{id}

გააგზავნეთ მხოლოდ ის, რისი შეცვლაც გსურთ: name, intervalSeconds, confirmations, enabled, config ან paused.

paused მოწმდება monitor:pause-ის მიმართ, დანარჩენი კი monitor:update-ის მიმართ, ცალ-ცალკე — გასაღები, რომელსაც პაუზის უფლება აქვს, მაგრამ რედაქტირებისა არა, პაუზას მაინც შეძლებს. ცარიელი ცვლილების გაგზავნა 400-ს იძლევა.

მონიტორი ხელახლა იკითხება და ბრუნდება, და არა თქვენი შეყვანილი აისახება უკან — ასე რომ ის, რასაც ხედავთ, შენახულია.

# Silence a monitor for the length of a deploy.
curl -X PATCH https://vitrinaengine.com/api/v1/monitors/$ID \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{"paused": true}'

DELETE /monitors/{id}

საჭიროებს monitor:delete-ს. პასუხობს { "data": { "id": "…", "deleted": true } }.

GET /hosts · POST /hosts

სერვერები მონიტორების დაჯგუფების მეორე გზაა: სამუშაო სივრცე ამბობს, ვისია მონიტორი, სერვერი კი — რაზე მუშაობს იგი. სრულიად არჩევითია — ანგარიში, რომელიც არასდროს შექმნის სერვერს, არაფერს კარგავს, და მონიტორების უმეტესობა სერვერს საერთოდ არ ასახელებს.

თითოეულ სერვერს აქვს status, pinned და spanning. status გამომდინარეობს მხოლოდ იმ მონიტორებიდან, რომლებიც მხოლოდ ამ სერვერზე მუშაობს. რამდენიმე მანქანაზე გაშლილი მონიტორი ითვლება spanning-ში და არცერთს არ აფერადებს: დატვირთვის გამანაწილებელი წერტილის შეფერხება ამბობს, რომ სერვისი გაფუჭდა და არა — რომელმა მანქანამ გააფუჭა. სერვერი, რომელსაც საკუთარი მონიტორი არ ჰყავს, პასუხობს "status": null-ს და არა up-ს.

POST საჭიროებს monitor:create-ს და name-ს. არჩევითი provider, address და notes თქვენია — პროდუქტი მათ არ იყენებს. სახელი, რომელიც უკვე არსებულს ემთხვევა (რეგისტრი და ბოლო წერტილი იგნორირდება), პასუხობს 409-ს.

GET /hosts/{id} · PATCH /hosts/{id} · DELETE /hosts/{id}

დეტალები შეიცავს სერვერს და მასზე არსებულ მონიტორებს, თითოეულს pinned ნიშნით, ხოლო როცა ის არ არის — alsoOn-ით: სხვა მანქანები, საიდანაც მონიტორი პასუხობს. სწორედ ამას კითხულობთ გადატვირთვამდე. DELETE ხსნის სერვერს, ხოლო მასზე არსებული ყველა მონიტორი აგრძელებს მუშაობას: სერვერს არც თავისი განრიგი აქვს და არც ისტორია.

POST /hosts/{id}/monitors · DELETE /hosts/{id}/monitors

ერთი მონიტორი სერვერზე ან სერვერიდან — monitorId-ით სხეულში ან ?monitorId=-ით. განზრახ არა მთელი სია: სააგენტოს ანგარიშზე ერთ სერვერზე რამდენიმე სამუშაო სივრცის მონიტორია, და ვინც „სიას“ ჩაანაცვლებდა, ჩაანაცვლებდა სტრიქონებს, რომლებიც არ უნახავს. ორივე მიმართულება იდემპოტენტურია.

GET /monitors/{id}/hosts · PUT /monitors/{id}/hosts

იმავე კავშირის მეორე მხარე და ეს უკვე მთელი სიაა: ეს კავშირები ერთ მონიტორს ეკუთვნის, ამიტომ მეორე ბოლოში არაფერია, რაც სხვა სამუშაო სივრცემ შეიძლება დაინახოს. გაგზავნეთ hostIds; ცარიელი მასივი ნამდვილი მოთხოვნაა და ნიშნავს, რომ მონიტორი კონკრეტულ სერვერზე არ მუშაობს. სხვისი იდენტიფიკატორები უარყოფის ნაცვლად უბრალოდ გამოტოვდება. ყოველი მონიტორის პასუხს ასევე აქვს hosts — ცარიელი, თუ არცერთი არაა.

GET /incidents

საჭიროებს incident:read-ს. იღებს ?status=-ს — ერთ-ერთს შემდეგთაგან: open, acknowledged, resolved ან suppressed — და ?open=true-ს იმ სამისთვის, რომლებიც გადაწყვეტილი არაა. ამოუცნობი სტატუსი იგნორირდება და არ უარიყოფა, ისევე როგორც ?limit= (ნაგულისხმევად 50) 200-ზე იჭრება და არ უარიყოფა.

თითოეული ატარებს id, monitorId, monitorName, title, cause, status, severity, startedAt, resolvedAt, durationSeconds, acknowledgedAt და rootIncidentId.

rootIncidentId არის ის ველი, რომელსაც უნდა უყუროთ, როცა შეტყობინებების ნაკადს აწყობთ. თუ ის შევსებულია, ეს ინციდენტი სხვის გავრცელების არეალშია: მონაცემთა ბაზის ჰოსტი ჩავარდა, ეს კი მის უკან მდგარი თორმეტი სერვისიდან ერთია. გამოტოვეთ ისინი და ერთ შეტყობინებას მიიღებთ ცამეტის ნაცვლად.

GET /incidents/{id}

ერთი ინციდენტი. საჭიროებს incident:read-ს. იგივე ველები, რაც სიაში, პლუს workspaceId.

ის არ აბრუნებს ინციდენტის ქრონოლოგიას — კომენტარები და სტატუსის ცვლილებები, რომლებიც პანელში ჩანს, ამ ბოლოწერტილზე არაა. თუ გჭირდებათ, გვითხარით და დაემატება; მათი აქ აღწერა მაშინ, როცა ისინი არ არსებობს, ამ ხარვეზზე უარესი იქნებოდა.

PATCH /incidents/{id}

გააგზავნეთ status მნიშვნელობით "acknowledged" ან "resolved", ან comment, ან ორივე. თითოეული საკუთარი უფლების მიმართ მოწმდება: incident:acknowledge, incident:resolve, incident:comment. კომენტარზე "publish": true-ს დამატება მას სტატუსის გვერდზე დებს და დამატებით საჭიროებს status_page:manage-ს.

# A runbook that fixed the thing itself can close its own incident.
curl -X PATCH https://vitrinaengine.com/api/v1/incidents/$ID \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "comment": "Restarted by runbook.", "publish": true}'

PUT /incidents/{id}/postmortem

წერს ან ანაცვლებს ინციდენტის ანალიზს. საჭიროა incident:resolve, და ინციდენტი უკვე მოგვარებული უნდა იყოს — წინააღმდეგ შემთხვევაში 409, კოდით incident_not_resolved. გამოგზავნეთ body Markdown-ში, ჰარეების მოკვეთის შემდეგ 1-დან 50 000 სიმბოლომდე (postmortem_required, postmortem_too_long). ინციდენტს ერთი ანალიზი აქვს, ასე რომ ყოველი გამოძახება წინას ანაცვლებს. პასუხი ინციდენტია, ისე, როგორც მას GET /incidents/{id} აბრუნებს.

GET /incidents/{id} მას postmortem: { body, authorName, updatedAt } სახით ან null-ად შეიცავს, სია კი — hasPostmortem-ს. body ასახეთ Markdown-ის სახით და არასოდეს HTML-ად: ეს ადამიანის აკრეფილი ტექსტია. ანალიზი შიდა დოკუმენტია და სტატუსის გვერდზე არასოდეს ჩანს.

curl -X PUT https://vitrinaengine.com/api/v1/incidents/$ID/postmortem \
  -H "Authorization: Bearer vte_…" \
  -H "Content-Type: application/json" \
  -d '{"body": "## What happened\n\nThe connection pool ran dry after a deploy."}'

GET /probes

თქვენი ორგანიზაციის საკუთარი კერძო ზონდები: id, name, lastSeenAt, version, hostname, monitorCount, revoked და createdAt. საჭიროა agent:read. ამას სთავაზობს მონიტორის ზონდის ამომრჩევი.

რეგიონის ველი არ არის და არც იქნება. ზონდს სახელით ირჩევთ; სად სრულდება მის უკან შემოწმება, ამას ჩვენ ვწყვეტთ და ვცვლით. გაუქმებული ზონდები revoked: true-თ ჩანს და მუშაობას აღარ იღებენ, ასე რომ ნუ შესთავაზებთ მათ.

GET /monitors/{id}/push-url

heartbeat მონიტორის პინგის URL, ხელახლა ნაჩვენები. საჭიროა monitor:read. url არის null ტიპისთვის, რომელსაც პინგი არ ეგზავნება, და ტოკენისთვის, რომლის გაშიფვრაც აღარ ხერხდება — მონიტორი მუშაობას აგრძელებს, ტოკენის განახლება პანელში კი ნაჩვენებ URL-ს გვაძლევს.

GET /organizations · PUT /organizations/active

ორგანიზაციები, რომელთა წევრიც შესული პირია, თითოეული მისი იქაური role-თ და active-ით მოქმედზე, და მათ შორის გადართვა. გამოგზავნეთ organizationId; პასუხი ახლა გამოყენებული წევრობაა.

მხოლოდ შესული სესიით. გასაღები ერთ წევრობას ეკუთვნის და იღებს 403-ს session_required-ით. გადართვა ამ პირის ყოველ სესიას გადაიტანს, პანელის ჩათვლით, ორგანიზაცია, რომლის წევრიც არ არის, კი 404-ს აბრუნებს.

POST /sms/enrolment · POST /sms/enrolment/confirm

დაარეგისტრირეთ თქვენი საკუთარი მობილური ნომერი SMS შეტყობინებებისთვის: გამოგზავნეთ phone (და სურვილისამებრ name), და მასზე ექვსნიშნა კოდს გამოვგზავნით; ეს code მეორე მარშრუტზე გამოგზავნეთ დასადასტურებლად. საჭიროა notification_channel:manage და შესული სესია — ნომერს ტელეფონის მფლობელი ამატებს, არასოდეს გასაღები.

ნომერი დაუდასტურებლად ინახება და არაფერს იღებს, ვიდრე კოდი არ დაბრუნდება. ხელახლა რეგისტრაცია თქვენს წინა ნომერს ანაცვლებს. უარები: sms_not_included (402, პაკეტში SMS არ შედის), not_a_phone_number, sms_country_unsupported, sms_route_not_open, verification_code_not_sent (502; ახალი კოდისთვის ხელახლა გამოიძახეთ), verification_code_malformed და verification_code_incorrect. წარმატებული დაწყება country-ს და caveat-ს შეიცავს — sender-replaced, registration-pending, unverified ან null —, რისი ჩვენებაც ღირს, ვიდრე ვინმე ნომერს ენდობა.

POST /channels/{id}/confirmation

ხელახლა აგზავნის ელფოსტის არხის დადასტურების წერილს. საჭიროა notification_channel:manage. ყოველი გამოძახება ახალ ბმულს ქმნის, წინა კი მუშაობას წყვეტს. sent: false ნიშნავს, რომ გასაგზავნი არაფერი იყო — მისამართი უკვე დადასტურებულია — და დადასტურებულ მისამართზე ამ გზით არასოდეს ხელახლა არ იწერება. თუ ფოსტის პროვაიდერმა გაგზავნაზე უარი თქვა, პასუხი 502-ია confirmation_not_sent-ით.

PATCH /workspaces/{id}

გადაარქმევს სამუშაო სივრცეს. საჭიროა workspace:update. name სავალდებულოა (1-დან 80 სიმბოლომდე), clientReference — არასავალდებულო; null მას წაშლის. slug არასოდეს იცვლება, რადგან ის სტატუსის გვერდების URL-ებშია. პასუხი სამუშაო სივრცეა ახლანდელ სახით.

POST /sourcemaps

ატვირთეთ source map, რომ მინიფიცირებული გამოძახებათა სტეკები გაიშალოს. საჭიროებს monitor:create-ს. სავალდებულოა projectRef (რიცხვი) და filename, აგრეთვე თავად რუკა — ან map-ად (JSON), ან mapGzipBase64-ად. არასავალდებულო: debugId და release.

გააგზავნეთ debug id ან release. რუკა, რომელსაც არცერთი აქვს, ვერცერთ გამოძახებათა სტეკს ვერ დაუკავშირდება და უსაქმოდ დარჩება. დაკავშირება ჯერ debugId-ით ხდება, შემდეგ release-ითა და ფაილის სახელით.

რუკები პრობლემის კითხვისას იშლება და არა ატვირთვისას, ამიტომ რუკა, რომელიც შეცდომების მოსვლის შემდეგ აიტვირთა, მაინც შველის — და ეს ჩვეულებრივი თანმიმდევრობაა.

POST /symbols

იგივე იდეა ნატიური აპლიკაციისთვის: ატვირთეთ iOS-ის .dSYM ან Android-ის R8 mapping.txt, რომ ავარიების სტეკები გაიშალოს. საჭიროებს monitor:create-ს. ოცი ატვირთვა საათში, და თითო პროექტზე ოცი ბილდის სიმბოლოები ინახება.

/sourcemaps-ისგან განსხვავებით, სხეული თავად gzip-შეკუმშული ფაილია, მეტამონაცემები კი სათაურებშია: X-Vitrina-Project-Ref, X-Vitrina-Platform (ios ან android), X-Vitrina-Symbol-Name და X-Vitrina-Release. dSYM ათეულობით მეგაბაიტია, base64 კი JSON-ველში გადაცემას მესამედით აძვირებს.

ორი პლატფორმა სხვადასხვანაირად ჯერდება. iOS-ის ფრეიმი ასახელებს იმ image-ის Mach-O UUID-ს, რომელსაც ეკუთვნის, ამიტომ iOS-ის ატვირთვას უნდა ახლდეს X-Vitrina-Debug-Ids და ზუსტად მასზე ჯერდება. R8 ასეთ იდენტიფიკატორს არ გამოსცემს, ამიტომ Android-ის mapping მხოლოდ release-ით ჯერდება — და ის ზუსტად ის უნდა იყოს, რასაც აპლიკაცია აცხადებს: <applicationId>@<versionName>+<versionCode>. ერთი ციფრი რომ აცდეს, ფრეიმები ისეთ ხაზებზე გაიშლება, რომლებიც დამაჯერებლად გამოიყურება და მცდარია.

იმავე ბილდის ხელახლა ატვირთვა მის სიმბოლოებს ჩაანაცვლებს და არ ჩავარდება, ასე რომ გამეორებული გამოშვების დავალება შეცდომა არაა. source map-ების მსგავსად, გაშლა პრობლემის წაკითხვისას ხდება.

GET /errors/projects

შეცდომების თვალთვალის პროექტები, რომლებიც ამ ანგარიშს აქვს. საჭიროებს monitor:read-ს. თითოეული ატარებს ref-ს — რიცხვს, რომელიც DSN-შია — პლუს publicKey, unresolved და eventsLast24h. მხოლოდ კითხვადია: პროექტი იქმნება გასაღებით, რომელიც მაინც უნდა ჩაისვას აპლიკაციის კონფიგურაციაში, ასე რომ აქ არაფერია, რასაც ბოლოწერტილი დაასრულებდა.

GET /errors/issues

დაჯგუფებული შეცდომები, უახლესი აქტივობით წინ. საჭიროებს monitor:read-ს. პრობლემა ანაბეჭდია და არა ცალკეული მოვლენა, ასე რომ ერთი და იმავე შეცდომის ათასი შემთხვევა ერთი სტრიქონია, სადაც timesSeen ათასია. ?status= ნაგულისხმევად unresolved-ია და ასევე იღებს resolved-ს, ignored-ს ან all-ს; ?project= ფილტრავს პროექტის იდენტიფიკატორით, ?q= ეძებს ტიპში, მნიშვნელობასა და გამომწვევში, ხოლო ?limit= 200-ით იზღუდება. spark ოცდაოთხი საათობრივი მთვლელია, უძველესიდან.

GET /errors/issues/{id}

ერთი პრობლემა თავისი სტეკით. საჭიროებს monitor:read-ს. exceptions არის SDK-ის საკუთარი ჯაჭვი — ბოლოს ნასროლი შეცდომა, მის წინ კი მისი გამომწვევები — და მისი ფრეიმები იშლება ნებისმიერი თქვენ მიერ ატვირთული source map-ის მიხედვით: იგივე გაშლა, რასაც პანელი აკეთებს, ასე რომ სკრიპტი და ადამიანი, რომელსაც ესაუბრებით, არასდროს სხვადასხვა სტეკს უყურებს. რუკა, რომლის გამოყენებაც ვერ ხერხდება, თავდაპირველ ფრეიმებზე ბრუნდება და მოთხოვნას არ აგდებს.

lastEvent განზრახ ატარებს ორ დროის ნიშნულს. occurredAt ის არის, რაც SDK-მ აღნიშნა, receivedAt კი ის, როცა მიღებამ ჩაწერა; მოწყობილობა, რომელიც ხაზგარეშე იყო, ან რიგი, რომელიც დაგროვდა, ზუსტად მათ შორის სხვაობაა.

PATCH /errors/issues/{id}

გადაწყვეტა, იგნორირება ან ხელახლა გახსნა: { "status": "resolved" }. საჭიროებს monitor:update-ს. ignoreHours შეიძლება ახლდეს ignored-ს, რომ იგნორირება მოგვიანებით თავისით მოიხსნას, და 90 დღით იზღუდება.

გადაწყვეტა იწერს release-ს, რომელშიც ის გადაწყდა, ასე რომ ძველი განთავსებიდან ჩამორჩენილი მოვლენა პრობლემას ხელახლა არ ხსნის. როცა SDK-მ release საერთოდ არ გამოგზავნა, შესადარებელი არაფერია და ნებისმიერი შემდგომი მოვლენა მას მართლაც ხელახლა ხსნის — როცა ჩამორჩენილს რეგრესიისგან ვერ გაარჩევ, უსაფრთხო დაშვებაა, რომ შეცდომა დაბრუნდა.

GET /analytics

ვებგვერდები, რომლებსაც ეს ანგარიში ზომავს. საჭიროებს monitor:read-ს. ატარებს publicId-ს — მნიშვნელობას, რომელიც სკრიპტის ტეგში ჯდება და განზრახ საჯაროა — პლუს viewsLast24h-ს და trafficAlerting-ს, რომელიც ჭეშმარიტია მანამ, სანამ საიტის ტრაფიკი იმაზე დაბალია, რასაც ის საათი ჩვეულებრივ ხედავს.

GET /analytics/{id}

ერთი საიტის რიცხვები, ცხრილისთვის ან ანგარიშისთვის. საჭიროებს monitor:read-ს. ?days= ნაგულისხმევად 7-ია და 365-ით იზღუდება. ?dimensions= იღებს მძიმით გამოყოფილ სიას შემდეგთაგან: path, referrer, country, browser, os, device, utm_source, utm_medium, utm_campaign და event; უცნობი მათგანი 400-ია და არა ცარიელი პასუხი, რადგან შეცდომით აკრეფილი სიტყვა, რომელიც არაფერს აბრუნებს, იკითხება როგორც „ტრაფიკი არ არის“.

ვიზიტორების მაჩვენებელს ჰქვია dailyUniqueVisitors, და ზუსტად ესაა. ის დღიური უნიკალურების ჯამია და სხვა ვერაფერი იქნება: საიდუმლო, რომელიც ვიზიტორის ჰეშის უკან დგას, თავისი UTC-დღის ბოლოს ნადგურდება, ასე რომ ვინც ორ დღეს შემოვიდა, ორჯერ ითვლება, და გასაღები, რომელიც მათ გააერთიანებდა, არ არსებობს. ეს კონფიდენციალურობის დიზაინის მუშაობაა და არა მიახლოება — მაგრამ ველი სახელად visitors 30-დღიან დიაპაზონთან ერთად გიბიძგებდათ, ისეთი რიცხვი გეჩვენებინათ, რომელიც სხვა რამეს ნიშნავს.

curl "https://vitrinaengine.com/api/v1/analytics/$ID?days=30&dimensions=path,referrer" \
  -H "Authorization: Bearer vte_…"

GET /billing

გეგმა და ის, სად ხდება მისი ანგარიშსწორება. საჭიროებს billing:read-ს. ატარებს plan, status, cadence, currentPeriodEnd, cancelAt, addOnPacks და ბოლო ათეულამდე ქვითარს.

source არის paddle, apple, manual ან none. ამას მნიშვნელობა აქვს: iOS-აპლიკაციაში ნაყიდი გამოწერა Apple-ის შესაცვლელია, და გეგმაც, ბარათიც და გაუქმებაც კლიენტის App Store-ის პარამეტრებში ცხოვრობს და არა აქ. canCheckoutOnWeb და canPurchaseInApp ამბობს, რომელი შეთავაზების ჩვენებაა უსაფრთხო, ასე რომ კლიენტს ეს წესი თავიდან არ უნდა გამოიყვანოს და არასწორად ვერ გამოიყვანს იმ მიმართულებით, სადაც ადამიანს ორჯერ ჩამოეჭრება.

GET /monitors/{id}/history

ერთი მონიტორის დღიური ხელმისაწვდომობა. საჭიროებს monitor:read-ს. იღებს days-ს, თქვენი გეგმის ისტორიის შენახვის ვადამდე.

გამოითვლება დღიური აგრეგატებიდან და არა ცალკეული შემოწმებების შედეგებიდან — სწორედ ამიტომ ის კვლავ პასუხობს იმ პერიოდებზე, რომელთა ნედლი შედეგებიც შენახვის ვადამ უკვე წაშალა.

GET /monitors/{id}/graph · GET /monitors/graphs

ერთი მონიტორის ბოლო საათები, საათ-საათ, ან ამ გასაღებისთვის ხილული ყველა მონიტორისა ერთ პასუხში — ის, რასაც დაფა ხატავს მონიტორის მწკრივსა და გვერდზე. საჭიროებს monitor:read-ს. იღებს hours-ს, ნაგულისხმევად 24, მაქსიმუმ 168.

uptime გრაფიკი თითოეული საათის წარმატებული შემოწმებების წილს შეიცავს, null-ით საათისთვის, როცა შემოწმება არ იყო; value გრაფიკი, რაოდენობითი ტიპებისთვის, ანათვლებს ერთეულიანი სერიების სახით შეიცავს. ფანჯრის ყოველი საათი წარმოდგენილია, ჩაიწერა რამე თუ არა, ასე რომ წყვეტა წყვეტად ჩანს. ანათვლები იგზავნება ისე, როგორც გაიზომა: raw სერიას ცნობილი მასშტაბი არ აქვს — დახატეთ ის საკუთარი უმაღლესი ანათვლის მიმართ და ეს წილი არასოდეს აჩვენეთ ანათვლად.

GET /monitors/{id}/channels · PUT /monitors/{id}/channels

რომელ არხებს აფრთხილებს ეს მონიტორი და მათი დაყენება. კითხვას სჭირდება notification_channel:read; ჩაწერას — monitor:update.

PUT მთელ ნაკრებს ანაცვლებს — გააგზავნეთ ყველა იმ არხის იდენტიფიკატორი, რომელიც გსურთ, და არა მხოლოდ ის, რასაც ამატებთ. ცარიელი მასივი ნიშნავს, რომ მონიტორი არავის აფრთხილებს: ეს კანონიერი სურვილია და ცუდი შემთხვევითობა.

GET /incidents/{id}/events

ერთი ინციდენტის ქრონოლოგია: მდგომარეობის ცვლილებები, დადასტურებები, კომენტარები, ესკალაციის საფეხურები. საჭიროებს incident:read-ს. ეს ის ქრონოლოგიაა, რომელსაც GET /incidents/{id} არ შეიცავს.

GET /channels · POST /channels

კითხვას სჭირდება notification_channel:read; შექმნას — notification_channel:manage. თითოეული ატარებს id, kind, name, target და workspaceId.

secret ბრუნდება მხოლოდ არხის შექმნისას და აღარასდროს. ეს ვებჰუკის ხელმოწერის გასაღებია; მისი ისეთ ადგილას შენახვა, საიდანაც უკან წაიკითხავდით, მხოლოდ კითხვის უფლების გასაღებს ხელმოწერილი მოთხოვნების გაყალბების საშუალებად აქცევდა.

შეგიძლიათ შექმნათ ის სახეები, რომელთა შექმნაც ადამიანს პანელში შეუძლია: email, webhook, telegram, slack, teams, discord, pagerduty და jsm. SMS, WhatsApp, თანამგზავრული და push-არხები თავად მიმღებს რეგისტრირდება და API-ით ვერ შეიქმნება — სწორედ ეს აქცევს მათ თანხმობად და არა ველად, რომელშიც ვიღაცამ რაღაც აკრიფა.

ელფოსტის არხი იქმნება დაუდასტურებლად და იღებს ერთ წერილს კითხვით, სურს თუ არა შეტყობინებები. სანამ არ დათანხმდება, სხვა არაფერი იგზავნება, ასე რომ მისი API-ით შექმნა თავისთავად მისამართს თქვენს სამორიგეო სიაში არ სვამს.

PATCH /channels/{id} · DELETE /channels/{id} · POST /channels/{id}/test

ყველას სჭირდება notification_channel:manage. სატესტო გაგზავნაზე უარი ეთქმევა მისამართს, რომელსაც დადასტურება არ გაუვლია — თორემ ის იქნებოდა შეუზღუდავი გზა, ეწეროთ მისამართზე, რომელსაც თანხმობა არ მოუცია, მხოლოდ სასარგებლო იარლიყით.

GET /status-pages · POST /status-pages

კითხვას სჭირდება status_page:read; ჩაწერას — status_page:manage. თითოეული ატარებს id, name, slug, visibility, customDomain, domainVerifiedAt, subscribersEnabled, componentCount, workspace და createdAt.

GET /status-pages/{id} · PATCH /status-pages/{id} · DELETE /status-pages/{id}

კითხვას სჭირდება status_page:read; შეცვლას ან წაშლას — status_page:manage.

POST /status-pages/{id}/components · DELETE /status-pages/{id}/components

მონიტორის დამატება გვერდზე ან მოხსნა. საჭიროებს status_page:manage-ს.

მონიტორი იმავე სამუშაო სივრცეში უნდა იყოს, რომელშიც გვერდია, და არა უბრალოდ იმავე ორგანიზაციაში. სააგენტოს ანგარიშში სწორედ ეს აჩერებს ერთი კლიენტის მონიტორის გამოქვეყნებას მეორე კლიენტის გვერდზე.

GET /workspaces · POST /workspaces · DELETE /workspaces/{id}

კითხვას სჭირდება workspace:read, დანარჩენს კი — თავ-თავისი უფლებები. თითოეული ატარებს id, name, slug, clientReference და isDefault.

შემოფარგლული წევრის გასაღები ხედავს მხოლოდ იმ სამუშაო სივრცეებს, რომლებითაც ეს წევრია შემოფარგლული. ნაგულისხმევი სამუშაო სივრცე ვერ წაიშლება.

GET /members · POST /members

კითხვას სჭირდება member:read; მოწვევას — member:invite. პასუხში members და invitations ცალ-ცალკეა — მოწვევამ, რომელიც არავის მიუღია, არავინ დაამატა, და მათი შერწყმა ისეთ ადგილების რაოდენობას მოგცემდათ, რომელიც თქვენს ანგარიშფაქტურას არ დაემთხვეოდა.

POST აგზავნის მოწვევას და ანგარიშს არ ქმნის. ის იღებს ელფოსტას, როლს და, სურვილისამებრ, workspaceIds-ს მათ შემოსაფარგლავად.

PATCH /members/{id} · DELETE /members/{id} · DELETE /invitations/{id}

როლის შეცვლას სჭირდება member:update_role; წაშლას — member:remove; მოწვევის გაუქმებას — member:invite.

წევრის წაშლა შლის მის პირად შეტყობინების არხებს — მის ტელეფონს, მის პირად ჩატს, მის მობილურ ნომერს — მის API-გასაღებებთან ერთად. საერთო არხებს ეს არ ეხება. ბოლო მფლობელი ვერ წაიშლება და ვერც როლს დაუქვეითებთ.

GET /maintenance · POST /maintenance · DELETE /maintenance

ფანჯრები, რომელთა განმავლობაშიც არავის იძახებენ. ნაგულისხმევად შემოწმებები კვლავ სრულდება და იწერება, ამიტომ ეს წუთები ხელმისაწვდომობაში ჩვეულებრივ ითვლება; keepChecking-ის false-ზე დაყენებისას ფანჯრის განმავლობაში არაფერი მოწმდება, რაც ისტორიაში ვარდნის ნაცვლად ხარვეზს ტოვებს. კითხვას სჭირდება incident:read; ჩაწერას — maintenance:manage.

ატარებს title, startsAt, endsAt, timezone, monitorIds, recurrenceRule, keepChecking, showOnStatusPage და notifySubscribers. განმეორებადი ფანჯარა ერთი ჩანაწერია და არა მრავალი.

წესი ფანჯარას იმავე ადგილობრივ დროზე იმეორებს მის საკუთარ timezone-ში, ასე რომ საათის გადაყვანისასაც ფანჯარა დაგეგმილ საათზე რჩება. იშლება FREQ=DAILY, FREQ=WEEKLY და FREQ=MONTHLY, სურვილისამებრ INTERVAL, COUNT, UNTIL და BYDAY ან BYMONTHDAY, რომელიც იმ დღეს ასახელებს, როცა თავად ფანჯარა იწყება. სხვა ნებისმიერი წესი უცვლელად ინახება და უცვლელადვე ბრუნდება და შეტყობინებებს მხოლოდ პირველ ჯერზე აჩერებს — ის არასოდეს გამოიცნობა.

GET /on-call

განრიგები, ესკალაციის პოლიტიკები, ჩანაცვლებები და ის, ვინც ახლა მორიგეობს. საჭიროებს oncall:read-ს.

onCallNow იმ წამში გამოითვლება, როცა კითხულობთ, ხოლო viaOverride ამბობს, ეს როტაციიდან მოვიდა თუ იმისგან, ვინც ვინმეს ანაცვლებს. unreachable ასახელებს მონაწილეებს, რომლებსაც არცერთი არხი არ აქვთ, რომლითაც მართლა მიწვდებოდნენ — და სწორედ ეს ის ჩავარდნაა, რომელიც ინციდენტამდე ღირს დაჭერად და არა მის დროს.

GET /agents · POST /agents · DELETE /agents · GET /agents/{id}/metrics

სერვერის აგენტები თქვენივე მანქანებიდან აწვდის პროცესორის, მეხსიერებისა და დისკის მაჩვენებლებს. რეგისტრაციას სჭირდება agent:enroll, კითხვას — agent:read, წაშლას — agent:delete.

რეგისტრაცია აბრუნებს ტოკენს, ერთხელ. სწორედ ამით ავთენტიფიცირდება აგენტი, ამიტომ შემდეგ ის აღარასდროს იკითხება.

GET /api-keys · POST /api-keys · DELETE /api-keys

კითხვას სჭირდება api_key:read; შექმნასა და გაუქმებას — api_key:manage. თითოეული ატარებს id, name, prefix, scopes, workspaceIds, owner, createdAt, lastUsedAt, expiresAt და revokedAt.

token ბრუნდება მხოლოდ შექმნისას. prefix ის ნაწილია, რომლის ჩვენებაც შეიძლება — და სწორედ ის გაძლევთ საშუალებას, სიაში ორი გასაღები ერთმანეთისგან გაარჩიოთ ისე, რომ არცერთი იკითხებოდეს.

გასაღები იმემკვიდრეობს იმ წევრობის როლსა და სამუშაო სივრცით შემოფარგვლას, რომელმაც ის შექმნა, ასე რომ გასაღები ვერ იქნება გზა იმ ზღვრის გვერდის ასავლელად, რომელიც მის ავტორს აქვს.

GET /audit

კონფიგურაციის ცვლილებები იმის მითითებით, ვინ გააკეთა და რა შეიცვალა. საჭიროებს audit_log:read-ს, რომელიც Business-იდან ზემოთაა.

გვერდებად იყოფა nextBefore-ით და არა გვერდის ნომრით, ასე რომ გვერდის საზღვარი კითხვის დროს არ იძვრება. ჩანაწერები ყველა გეგმაზე იწერება — გეგმა კითხვას ზღუდავს, ასე რომ განახლება მთელ ისტორიას ხსნის და არა ახლიდან იწყებს მას.

სააუთენტიფიკაციო მონაცემები, ჰეშები და საიდუმლოები changes-ში არასდროს იწერება.

GET /me

ვინ არის ეს გასაღები, რას სწვდება და რას უშვებს გეგმა. უფლება არ სჭირდება — ყოველ გასაღებს საკუთარი თავის აღწერა შეუძლია.

ატარებს user, organization, membership(როლი და სამუშაო სივრცით შემოფარგვლა), entitlements (გეგმის გამოთვლილი ზღვრები, უკვე ჩაკეცილი დამატებითი პაკეტებით) და usage. გამოიყენეთ, რომ ზღვარი შექმნის მცდელობამდე შეამოწმოთ და არა უარის შემდეგ.

სესია დამატებით იღებს organizations-ს, სადაც ჩამოთვლილია ყველა ორგანიზაცია, რომელსაც ეს ადამიანი ეკუთვნის. API-გასაღები არა: გასაღები ერთ წევრობაზე გაიცემა და მითაა შემოფარგლული, ასე რომ დანარჩენების ჩამოთვლა გაასაჯაროებდა ორგანიზაციებს, რომლებსაც ეს სააუთენტიფიკაციო მონაცემი ვერ სწვდება.

DELETE /account

შლის ორგანიზაციას და ყველაფერს, რაც მასშია. ამას უფლების არცერთი კონსტანტა არ იცავს, რადგან შემოწმება თავად მფლობელობაა: ვინც მფლობელი არაა, მას უარი ეთქმევა.

ეს შეუქცევადია და პაუზა არაა. გამოიყენეთ გააზრებულად.

POST /billing/apple/verify

ადასტურებს ჩვენივე მობილურ აპლიკაციაში შესრულებულ შესყიდვას. საჭიროებს billing:manage-ს.

აღწერილია სისრულისთვის და არა გამოსაყენებლად: მისი გამოძახება მხოლოდ იმ ქვითრითაა შესაძლებელი, რომელიც Apple-მა ჩვენს აპლიკაციას გამოუწერა, ასე რომ მესამე მხარის ინტეგრაციას მისით არაფერი ესაქმება. აქ იმიტომაა ჩამოთვლილი, რომ მარშრუტი, რომელიც არსებობს და არსად აღწერილა, ვერ გაირჩევა იმისგან, რომელიც ვიღაცას დაავიწყდა.

GET /

ინდექსი. ჩამოთვლის მარშრუტებს, რომლებსაც ეს დანერგვა ემსახურება — ეს ამ გვერდის მანქანურად წასაკითხი ვერსიაა და ყოველთვის მიმდინარე, რადგან გენერირდება იმისგან, რაც რეალურად არის ჩართული.

ინციდენტების არხი (RSS და Atom)

თქვენი ანგარიშის ყველა ინციდენტი არხად — წამკითხველისთვის და არა კლიენტის ბიბლიოთეკისთვის. მისამართს ქმნით პანელში, განყოფილებაში პარამეტრები → შეტყობინებები:

https://vitrinaengine.com/feeds/incidents/vtf_…/feed.xml
https://vitrinaengine.com/feeds/incidents/vtf_…/atom.xml

მისამართი თავად არის საიდუმლო. გასაგზავნი სათაური არ არსებობს: ვისაც ბმული აქვს, კითხულობს ანგარიშის ყველა ინციდენტს, ყველა სამუშაო სივრცეში. პანელში ის ყოველთვის ხელახლა ჩანს, რადგან წამკითხველში ცხოვრობს, რომელსაც ვიღაც ოდესმე თავიდან დააყენებს — და მისი შეცვლა ან გაუქმება შესაძლებელია, ძალაში მომდევნო მოთხოვნიდან და არა მაშინ, როცა ქეში ამოიწურება.

მასში მხოლოდ ინციდენტის დონის ფაქტებია: მონიტორის სახელი, მიზეზი, სიმძიმე, სტატუსი, გახსნისა და დახურვის დრო და ის განახლებები, რომლებიც საჯაროდ მონიშნეს. არასდროს — განხილვა, არასდროს — მონიტორის კონფიგურაცია და არასდროს ის, საიდან წავიდა შემოწმება. წამკითხველების უმეტესობა სხვისი სერვერებით სინქრონდება, ამიტომ დოკუმენტი ისე დაიწერა, თითქოს თქვენს შენობას ტოვებს — რადგან ტოვებს.

წუთში ერთხელ გამოკითხვა ნორმაა. ერთ მისამართზე წუთში სამოც მოთხოვნაზე მეტის შემდეგ პასუხობს 429-ს, ხოლო მისამართი, რომელიც არასდროს ყოფილა ნამდვილი, შეიცვალა ან გაუქმდა, პასუხობს 404-ს — სამივე შემთხვევაში ერთი და იგივე პასუხი, რომ მისით ვერ გაიგონ, რომელი ტოკენები იყო ოდესმე ნამდვილი.

რას არ აბრუნებს ეს API განზრახ

• მონიტორის config-ს. ის შეიძლება სააუთენტიფიკაციო მონაცემებს შეიცავდეს.
• რომელი რეგიონიდან შესრულდა შემოწმება. საიდან ვამოწმებთ, ჩვენ ვწყვეტთ და ჩვენვე ვცვლით, სანამ ზონდები თავსდება და გადაადგილდება. ეს იქნებოდა დაპირება ჩვენს ინფრასტრუქტურაზე, რომლითაც ვერაფერს გააკეთებდით, და პროდუქტში სხვაგან არსად ჩანს.

Exporting your data

GET /export/{entity}

ერთი სახის სტრიქონები, CSV-ად ან JSON-ად. entity არის monitors, hosts, status-pages, notification-channels, members, incidents, incident-events, postmortems, audit-log, error-issues, uptime-daily, uptime-hourly ან analytics-hourly. სხვა ყველაფერი პასუხობს 404-ით.

format არის csv (ნაგულისხმევი) ან json. from და to არის RFC 3339 დროის ნიშნულები. bom CSV-ს წინ უმატებს UTF-8 ბაიტების რიგის ნიშანს: Excel-ს ის სჭირდება არა-ASCII სახელებისთვის, სკრიპტული ენების უმეტესობა კი მას პირველი სვეტის სათაურის ნაწილად კითხულობს — ამიტომ ნაგულისხმევად გამორთულია.

GET /export

ყველაფერი, რისი წაკითხვაც გასაღებს შეუძლია, zip-ად: თითო ფაილი თითო ერთეულზე, პლუს manifest.json — რა არის არქივში, რამდენი სტრიქონია თითო ფაილში და რომელი ერთეულები აკლია. რასაც გასაღების როლი ვერ კითხულობს, გამოტოვებულია და არა მთელი მოთხოვნის უარყოფა; მანიფესტი კი ამას ჩუმად მოხდენას უშლის ხელს.

What an export does not contain

ექსპორტი არაფერს შეიცავს, რაც ავთენტიფიკაციას ახდენს: არც არხების კონფიგურაციას, არც heartbeat-ის ტოკენებს, არც პაროლების ჰეშებს. მონიტორის კონფიგურაცია შედის, ოღონდ ყველაფრის გარეშე, რაც სერტიფიკატს ჰგავს — მოთხოვნის სხეული, სათაურები, SNMP community, საფოსტო ყუთის მონაცემები. ნედლი შემოწმების შედეგებიც არ არის: მათ შენახვის ვადა შლის, ამიტომ ხელმისაწვდომობა აგრეგატებიდან მოდის.

Size, and the one refusal you may meet

საათობრივი სერიები შეზღუდულია 92 დღით ერთ მოთხოვნაზე; უფრო ფართო ფანჯარა უარყოფილია კოდით export_window_too_wide, და არა ჩუმად იჭრება. ცალკე ლიმიტი: 6 ექსპორტი საათში ორგანიზაციაზე.

ვერსიები

ვერსია გზაშია მითითებული. პასუხებს ველები დაემატება — უცნობებს მოეპყარით როგორც გამოსატოვებელს და არა როგორც შეცდომას — მაგრამ v1-იდან არაფერი წაიშლება და მასში არაფერი შეიცვლის მნიშვნელობას.

რამე აკლია?

შესაძლებლობების ნაკრები განზრახ მცირეა: ის ფარავს კედლის დაფას, შეჯამებას მესენჯერში და განთავსების სკრიპტს, რომელიც მონიტორს გამოშვების ხანგრძლივობით ჩუმდება. თუ რაღაცას აკეთებთ, რასაც ის ვერ სწვდება, მოგვწერეთ support@vitrinaengine.com-ზე — იმის ცოდნა, რაც ხალხს მართლა სჭირდება, სწორედ ისაა, რითიც შემდეგი ბოლოწერტილი შეირჩევა.

ფასები · მომსახურების პირობები