---
title: "KongNet Telco API"
url: "https://kongnet.kongai.uk/apis/kongnet-telco-api-1/versions/3d9e2c10-cf93-4e6e-8bf8-2129457a6aa5"
---

# KongNet Telco API

OpenAPI specification document.

```json
{"openapi":"3.1.0","info":{"title":"KongNet Telco API","description":"Customer, product, network, ticket and knowledge base operations for the KongNet support agent. The customer is identified by the gateway, never by a parameter.","version":"1.0.0"},"paths":{"/me":{"get":{"tags":["customer"],"summary":"Get the logged in customer's profile","description":"Use this first when you need the customer's name, tier, address, postcode, contact preference or whether they are flagged as vulnerable. Returns no account numbers.","operationId":"get_my_profile","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/products":{"get":{"tags":["customer"],"summary":"Get the customer's broadband package and add-ons","description":"Returns the package name, speeds, minimum guaranteed speed, router model, TV or mobile add-ons and the contract end date. Use it before quoting any speed or price.","operationId":"get_my_products","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/bills":{"get":{"tags":["customer"],"summary":"Get recent bills and the current balance","description":"Returns the last bills (amount in pence, status paid or overdue, due date), the outstanding balance and whether service is restricted for non payment.","operationId":"get_my_bills","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":12,"minimum":1,"description":"How many bills to return, newest first","default":3,"title":"Limit"},"description":"How many bills to return, newest first"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me/service-health":{"get":{"tags":["customer"],"summary":"Get the customer's line and router health","description":"Returns line sync speeds against the package, drops and errors in the last 24 hours, whether the router is online, the last reboot time and wifi channel details. Use it to decide whether a problem is the line, the router or wifi.","operationId":"get_service_health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/network-status":{"get":{"tags":["customer"],"summary":"Check for outages and planned work at the customer's postcode","description":"Returns live incidents and planned work affecting the customer's postcode, each with status, summary and the estimated fix time. Always call this before saying anything about an outage or a fix time.","operationId":"get_network_status","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/me/tickets":{"get":{"tags":["tickets"],"summary":"List the customer's support tickets","description":"Returns the customer's tickets, newest first, with reference, category, status and summary. Call this before creating a ticket so you can add a note to an existing open one instead of raising a duplicate.","operationId":"list_my_tickets","parameters":[{"name":"status","in":"query","required":false,"schema":{"enum":["open","closed","all"],"type":"string","description":"Filter by status","default":"all","title":"Status"},"description":"Filter by status"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["tickets"],"summary":"Create a support ticket for the customer","description":"Raises a ticket after troubleshooting has not fixed the problem and the customer has confirmed. Include steps tried and diagnostics. If an open ticket already exists in the same category the request is rejected with 409 and the existing reference: add a note to that ticket instead.","operationId":"create_ticket","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tickets/{ticket_id}":{"get":{"tags":["tickets"],"summary":"Get one ticket with its notes","description":"Returns full ticket details including steps tried, diagnostics and notes. Only the ticket owner or staff can read it.","operationId":"get_ticket","parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","title":"Ticket Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tickets/{ticket_id}/notes":{"post":{"tags":["tickets"],"summary":"Add a note to an existing ticket","description":"Appends an update to a ticket the customer owns. Use this instead of creating a second ticket for the same problem.","operationId":"add_ticket_note","parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","title":"Ticket Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tickets/{ticket_id}/close":{"post":{"tags":["staff"],"summary":"Close a ticket (staff only)","description":"Marks a ticket closed. Staff only. Customers cannot close their own tickets through the agent.","operationId":"close_ticket","parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","title":"Ticket Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me/credits":{"post":{"tags":["staff"],"summary":"Apply a goodwill credit to the account (staff only)","description":"Applies a credit in pence, capped at 5000, with a reason. Staff only. Never promise a credit to a customer before staff have approved it.","operationId":"apply_account_credit","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/kb/search":{"get":{"tags":["kb"],"summary":"Search help articles","description":"Full text search over KongNet troubleshooting articles. Use two to four plain words such as 'slow wifi evening' or 'red light'. Returns article ids, titles, a snippet and a score. Follow up with get_article for the steps.","operationId":"search_knowledge_base","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120,"description":"Search words","title":"Q"},"description":"Search words"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Maximum results","default":3,"title":"Limit"},"description":"Maximum results"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/kb/articles/{article_id}":{"get":{"tags":["kb"],"summary":"Get a help article with numbered steps","description":"Returns the article title, which router models and packages it applies to, and the numbered steps to read back to the customer.","operationId":"get_article","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CreditCreate":{"properties":{"amount_pence":{"type":"integer","maximum":5000,"exclusiveMinimum":0,"title":"Amount Pence","description":"Credit in pence, capped at 5000"},"reason":{"type":"string","maxLength":280,"minLength":5,"title":"Reason","description":"Why the credit is being applied"}},"type":"object","required":["amount_pence","reason"],"title":"CreditCreate"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NoteCreate":{"properties":{"text":{"type":"string","maxLength":4000,"minLength":1,"title":"Text","description":"Note to add to the ticket"}},"type":"object","required":["text"],"title":"NoteCreate"},"TicketCreate":{"properties":{"category":{"type":"string","enum":["outage","connection","wifi","speed","tv","billing","account","other"],"title":"Category","description":"Ticket category"},"summary":{"type":"string","maxLength":140,"minLength":5,"title":"Summary","description":"One line summary in the customer's words"},"details":{"type":"string","maxLength":4000,"title":"Details","description":"What the customer reported and what was found","default":""},"steps_tried":{"items":{"type":"string"},"type":"array","title":"Steps Tried","description":"Troubleshooting steps already tried, in order"},"diagnostics":{"additionalProperties":true,"type":"object","title":"Diagnostics","description":"Results from line test or wifi scan, if run"},"model_alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Alias","description":"Model alias that handled the conversation"},"trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trace Id","description":"Gateway trace id for the conversation"}},"type":"object","required":["category","summary"],"title":"TicketCreate"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```