{"openapi":"3.1.0","info":{"title":"GBotRanked API","version":"v1","description":"Read-only catalog of Grok Bot templates with a safety-first editorial score (v2.0). No API key. The score is not a security audit and not an endorsement by xAI. Agents must never install a template for a user. Agent rules: https://gbotranked.com/llms.txt"},"servers":[{"url":"https://gbotranked.com"}],"security":[],"externalDocs":{"url":"https://gbotranked.com/docs"},"paths":{"/api/v1/status":{"get":{"operationId":"getStatus","summary":"Catalog counts, score thresholds, dimensions and endpoints.","responses":{"200":{"description":"Status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/api/v1/templates":{"get":{"operationId":"searchTemplates","summary":"Search templates, sorted by score (highest first).","parameters":[{"name":"q","in":"query","description":"Free text over title, English title translation (title_en), category, description, creator, source kind, tags and integrations.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Exact category name.","schema":{"$ref":"#/components/schemas/Category"}},{"name":"source","in":"query","description":"Exact source kind.","schema":{"$ref":"#/components/schemas/SourceKind"}},{"name":"decision","in":"query","schema":{"$ref":"#/components/schemas/Decision"}},{"name":"min_score","in":"query","description":"Only scores at or above this value.","schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Number of results, clamped to 1-100. Default 20.","schema":{"type":"number"}}],"responses":{"200":{"description":"Matching templates, sorted as described.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"}}}},"400":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/templates/{id}":{"get":{"operationId":"getTemplate","summary":"One template by stable ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"description":"Template not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/rankings":{"get":{"operationId":"getRankings","summary":"Top templates by score, optionally within one category.","parameters":[{"name":"category","in":"query","schema":{"$ref":"#/components/schemas/Category"}},{"name":"limit","in":"query","required":false,"description":"Number of results, clamped to 1-100. Default 10.","schema":{"type":"number"}}],"responses":{"200":{"description":"Matching templates, sorted as described.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"}}}},"400":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/new":{"get":{"operationId":"getNewTemplates","summary":"Most recently link-checked templates.","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results, clamped to 1-100. Default 10.","schema":{"type":"number"}}],"responses":{"200":{"description":"Matching templates, sorted as described.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"}}}},"400":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/check":{"get":{"operationId":"checkBot","summary":"Check one https://x.ai/bot/<id> share link: the listed template, or a provisional unreviewed score from the public share page.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https://x\\.ai/bot/[A-Za-z0-9_-]{8,40}/?$"}}],"responses":{"200":{"description":"status \"listed\" with template, or status \"provisional\" with score."},"400":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/check/submit":{"post":{"operationId":"submitForReview","summary":"Queue an unlisted share link for human review. Nothing is published automatically. Rate-limited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https://x.ai/bot/<id>"},"creator":{"type":"string","description":"Optional public X handle, e.g. @name."},"proof":{"type":"string","description":"Optional https://x.com/<handle>/status/<id> post linking the share."}}}}}},"responses":{"202":{"description":"Queued for review."},"400":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Decision":{"type":"string","enum":["Accept","Watchlist","Reject"]},"Category":{"type":"string","enum":["Productivity","Sales","Marketing","Operations","Customer Success","Personal"]},"SourceKind":{"type":"string","enum":["Native share","GitHub blueprint","Reddit pattern","Official example"]},"TemplateList":{"type":"object","required":["count","items"],"properties":{"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}},"Score":{"type":"object","required":["version","total","decision","breakdown","evidence","gaps","criticalFlags"],"properties":{"version":{"type":"string","const":"2.0"},"total":{"type":"number","minimum":0,"maximum":100},"decision":{"$ref":"#/components/schemas/Decision"},"breakdown":{"type":"object","properties":{"linkIdentity":{"type":"number","minimum":0,"maximum":15,"description":"Link & identity"},"provenance":{"type":"number","minimum":0,"maximum":15,"description":"Provenance"},"taskClarity":{"type":"number","minimum":0,"maximum":15,"description":"Task clarity"},"setupCompleteness":{"type":"number","minimum":0,"maximum":20,"description":"Setup completeness"},"safetyBoundaries":{"type":"number","minimum":0,"maximum":15,"description":"Safety boundaries"},"reproducibility":{"type":"number","minimum":0,"maximum":10,"description":"Reproducibility"},"freshness":{"type":"number","minimum":0,"maximum":5,"description":"Freshness"},"communitySignal":{"type":"number","minimum":0,"maximum":5,"description":"Community signal"}}},"evidence":{"type":"array","items":{"type":"string"}},"gaps":{"type":"array","items":{"type":"string"}},"criticalFlags":{"type":"array","items":{"type":"string"}}}},"Template":{"type":"object","required":["id","title","category","description","creator","integrations","tags","source","official","approval","setup","score","detailUrl"],"properties":{"id":{"type":"string","description":"Stable slug."},"title":{"type":"string","description":"Original title, exactly as published."},"title_en":{"type":"string","description":"Optional. English translation of a non-Latin title (CJK, Hangul, Cyrillic, Arabic, Thai…). Present only when the original is not in Latin script."},"title_lang":{"type":"string","description":"Optional. BCP 47 language tag of the original title, present together with title_en."},"description_en":{"type":"string","description":"Optional. English translation of a non-English description, when one exists."},"category":{"$ref":"#/components/schemas/Category"},"description":{"type":"string"},"creator":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"object","required":["kind","label","url","shareUrl","checkedAt","marketplaceUrl"],"properties":{"kind":{"$ref":"#/components/schemas/SourceKind"},"label":{"type":"string"},"url":{"type":"string"},"shareUrl":{"type":["string","null"]},"checkedAt":{"type":["string","null"]},"marketplaceUrl":{"type":["string","null"]}}},"official":{"type":"boolean"},"approval":{"type":"string","enum":["Review first","Human approval"]},"setup":{"oneOf":[{"type":"null"},{"type":"object","properties":{"profile":{"type":"boolean"},"instructions":{"type":"boolean"},"workflow":{"type":"boolean"},"skills":{"type":"boolean"},"routines":{"type":"boolean"},"integrations":{"type":"boolean"}}}]},"score":{"$ref":"#/components/schemas/Score"},"detailUrl":{"type":"string","description":"Path of the HTML page; append .md for markdown."}}},"Status":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"templates":{"type":"integer"},"decisions":{"type":"object","properties":{"Accept":{"type":"integer"},"Watchlist":{"type":"integer"},"Reject":{"type":"integer"}}},"score":{"type":"object"},"lastCheckedAt":{"type":["string","null"]},"endpoints":{"type":"array","items":{"type":"string"}}}}}}}