{"openapi":"3.1.0","info":{"title":"Imara Cloud API","version":"v1","summary":"Manage hosting accounts, billing, domains and support programmatically.","description":"Authenticate with a bearer token created under **Client Area > Security > API Tokens**.\n\nAll responses are JSON. Every endpoint is scoped to the account that owns the token — a token can never read or modify another account's data.\n\nRate limited per token; remaining quota is returned in the `X-RateLimit-Remaining` header.\n\nAI agents can alternatively use the MCP endpoint at `https://host.mrbismarck.co.ke/mcp`, which exposes the same capabilities as callable tools over JSON-RPC 2.0.","contact":{"name":"Imara Cloud Support","url":"https://host.mrbismarck.co.ke/support","email":"mrbismarck85@gmail.com"},"license":{"name":"Commercial","url":"https://host.mrbismarck.co.ke/terms"}},"servers":[{"url":"https://host.mrbismarck.co.ke","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account","description":"Who the token belongs to"},{"name":"Billing","description":"Invoices and payments"},{"name":"Services","description":"Hosting services"},{"name":"Domains","description":"Domain names"},{"name":"Support","description":"Tickets"},{"name":"MCP","description":"Model Context Protocol endpoint for AI agents"}],"paths":{"/api/v1/whoami":{"get":{"tags":["Account"],"summary":"Identify the token holder","operationId":"whoami","responses":{"200":{"description":"The authenticated account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/invoices":{"get":{"tags":["Billing"],"summary":"List invoices","operationId":"listInvoices","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["paid","unpaid","cancelled"]},"description":"Filter by status"}],"responses":{"200":{"description":"Invoices on this account","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/invoices/{id}":{"get":{"tags":["Billing"],"summary":"Get one invoice","operationId":"getInvoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Resource ID"}],"responses":{"200":{"description":"The invoice, with line items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/services":{"get":{"tags":["Services"],"summary":"List hosting services","operationId":"listServices","responses":{"200":{"description":"Services on this account","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/domains":{"get":{"tags":["Domains"],"summary":"List domains","operationId":"listDomains","responses":{"200":{"description":"Domains on this account","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tickets":{"get":{"tags":["Support"],"summary":"List support tickets","operationId":"listTickets","responses":{"200":{"description":"Tickets on this account","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Ticket"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Support"],"summary":"Open a support ticket","operationId":"openTicket","description":"The department sets the ticket number prefix: Billing BILS-, Support SURP-, General Inquiries TKT-, Admin ADMN-, Sales SLS-, Abuse ABUS-.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","message"],"properties":{"subject":{"type":"string","example":"Cannot access webmail"},"message":{"type":"string","example":"Webmail returns a 500 error."},"department":{"type":"string","example":"Support"},"priority":{"type":"string","enum":["low","medium","high","urgent"]}}}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/tokens":{"post":{"tags":["Account"],"summary":"Issue a new API token","operationId":"issueToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"ci-pipeline"},"abilities":{"type":"array","items":{"type":"string"}},"ttl_days":{"type":"integer","nullable":true,"example":90}}}}}},"responses":{"201":{"description":"The new token, shown once only","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"MCP JSON-RPC 2.0 endpoint","operationId":"mcp","description":"Model Context Protocol over streamable HTTP. Call initialize, then tools/list, then tools/call. Point any MCP-capable AI client at this URL with the same bearer token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"integer","example":1},"method":{"type":"string","example":"tools/call"},"params":{"type":"object"}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"account_summary","arguments":{}}}}}},"responses":{"200":{"description":"JSON-RPC result","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/mcp/discover":{"get":{"tags":["MCP"],"summary":"Discover MCP tools (public)","operationId":"mcpDiscover","security":[],"responses":{"200":{"description":"Server metadata and tool catalogue","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token, e.g. Authorization: Bearer mrb_xxxxx"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"Invalid or expired token"}}},"Account":{"type":"object","properties":{"id":{"type":"integer","example":42},"first_name":{"type":"string","example":"Amina"},"last_name":{"type":"string","example":"Otieno"},"email":{"type":"string","format":"email","example":"amina@example.co.ke"},"company":{"type":"string","example":"Otieno Media"},"country":{"type":"string","example":"KE"},"currency":{"type":"string","example":"KES"},"credit":{"type":"number","format":"float","example":2500},"status":{"type":"string","enum":["active","inactive","suspended","banned"]}}},"Invoice":{"type":"object","properties":{"id":{"type":"integer","example":1042},"invoice_number":{"type":"string","example":"INV-2026-1042"},"status":{"type":"string","enum":["paid","unpaid","cancelled"]},"currency":{"type":"string","example":"KES"},"total":{"type":"number","format":"float","example":5800},"amount_paid":{"type":"number","format":"float","example":0},"balance_due":{"type":"number","format":"float","example":5800},"due_date":{"type":"string","format":"date"},"paid_date":{"type":"string","format":"date-time","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","example":"Starter Hosting - monthly"},"amount":{"type":"number","format":"float","example":1500},"quantity":{"type":"integer","example":1}}}}}},"Service":{"type":"object","properties":{"id":{"type":"integer","example":88},"product":{"type":"string","example":"Starter Hosting"},"domain":{"type":"string","example":"example.co.ke"},"status":{"type":"string","enum":["pending","active","suspended","terminated","cancelled"]},"billing_cycle":{"type":"string","enum":["monthly","quarterly","semiannually","annually","biennially","triennially"]},"amount":{"type":"number","format":"float","example":1500},"next_due_date":{"type":"string","format":"date"},"server":{"type":"string","example":"srv1"}}},"Domain":{"type":"object","properties":{"id":{"type":"integer","example":17},"domain":{"type":"string","example":"example.co.ke"},"registrar":{"type":"string","example":"KENIC"},"expiry_date":{"type":"string","format":"date"},"days_until_expiry":{"type":"integer","example":61},"auto_renew":{"type":"boolean","example":true},"status":{"type":"string","example":"active"}}},"Ticket":{"type":"object","properties":{"id":{"type":"integer","example":301},"ticket_number":{"type":"string","example":"SURP-20260731-0042"},"department":{"type":"string","example":"Support"},"subject":{"type":"string","example":"Cannot access webmail"},"status":{"type":"string","enum":["open","answered","customer-reply","on-hold","closed"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"last_reply_at":{"type":"string","format":"date-time"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}