{"openapi":"3.1.0","info":{"title":"Beacon Mobile Account API","version":"1.0.0","description":"Demo wireless-carrier API for a customer-facing AI agent: account, lines, plans, devices, usage, billing, support, and network status. Plans/devices/network are public; everything else needs a customer bearer token."},"servers":[{"url":"https://telecom.cvlsoft.net"}],"components":{"securitySchemes":{"customerToken":{"type":"http","scheme":"bearer","description":"Per-customer token. Demo: bm_tok_ava, bm_tok_marcus, bm_tok_priya."}}},"security":[{"customerToken":[]}],"paths":{"/api/me":{"get":{"summary":"Account overview: profile, lines, balance due"}},"/api/plans":{"get":{"summary":"List plans","security":[]}},"/api/plans/{id}":{"get":{"summary":"Get a plan by UUID or slug","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/devices":{"get":{"summary":"List devices for upgrade","security":[]}},"/api/devices/{id}":{"get":{"summary":"Get a device by UUID or slug","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/lines":{"get":{"summary":"List the account's lines"},"post":{"summary":"Add a new line","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planId"],"properties":{"planId":{"type":"string","description":"Plan UUID or slug"},"nickname":{"type":"string"}}}}}}}},"/api/lines/{id}":{"get":{"summary":"Get a line (id = UUID, nickname, or phone number)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"summary":"Rename or suspend/resume a line","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]}}}}}}}},"/api/lines/{id}/plan":{"post":{"summary":"Change a line's plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planId"],"properties":{"planId":{"type":"string"}}}}}}}},"/api/lines/{id}/upgrade":{"get":{"summary":"Device-upgrade eligibility + options for a line","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/lines/{id}/device":{"post":{"summary":"Upgrade a line to a new device (24-mo installment)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deviceId"],"properties":{"deviceId":{"type":"string"}}}}}}}},"/api/usage":{"get":{"summary":"Data usage this cycle for all lines, or one via ?lineId=","parameters":[{"name":"lineId","in":"query","schema":{"type":"string"},"description":"UUID, nickname, or phone number"}]}},"/api/bills":{"get":{"summary":"List bills, newest first"}},"/api/bills/{id}":{"get":{"summary":"Get a bill (UUID or invoice number) with line items — use to explain charges","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/bills/{id}/pay":{"post":{"summary":"Pay a due bill (demo: marks it paid)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/tickets":{"get":{"summary":"List support tickets"},"post":{"summary":"Open a support ticket","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject"],"properties":{"category":{"type":"string","enum":["billing","network","device","account"]},"subject":{"type":"string"},"body":{"type":"string"}}}}}}}},"/api/network":{"get":{"summary":"Network/outage status for a ZIP (defaults to billing ZIP)","security":[],"parameters":[{"name":"zip","in":"query","schema":{"type":"string"}}]}},"/api/network/report":{"post":{"summary":"Report a network problem (opens a ticket)","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"zip":{"type":"string"},"note":{"type":"string"}}}}}}}}}}