{"openapi":"3.1.0","info":{"title":"LightningBytes API","version":"1.0.0","description":"Programmatic control over proxy sub-users, endpoints, usage and account balances. Authenticate with a Bearer token created in the dashboard's API tab. Operational only: the API can never buy traffic, change plans or read invoices."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account"},{"name":"Catalog"},{"name":"Users"},{"name":"Endpoints"},{"name":"Usage"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sk-lb_...","description":"A token created in the dashboard's API tab, e.g. `Authorization: Bearer sk-lb_...`."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ScopePair":{"type":"object","required":["product","supplier"],"properties":{"product":{"type":"string"},"supplier":{"type":"string"}}},"CreateUserRequest":{"type":"object","required":["label","services"],"properties":{"label":{"type":"string","minLength":1,"maxLength":64},"services":{"type":"array","minItems":1,"items":{"type":"object","required":["product"],"properties":{"product":{"type":"string"},"supplier":{"type":"string"},"mode":{"type":"string","enum":["pooled","reserved"]},"gb":{"type":"number","minimum":0}}}}}}}},"paths":{"/api/v1/me":{"get":{"summary":"The caller's token identity and effective scope.","tags":["Account"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/products":{"get":{"summary":"In-scope products with balance and usage.","tags":["Catalog"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suppliers":{"get":{"summary":"In-scope suppliers with their products and capabilities.","tags":["Catalog"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/locations":{"get":{"summary":"Targeting options (countries, targeting keys) for a product.","tags":["Catalog"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users":{"get":{"summary":"List the account's sub-users.","tags":["Users"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a sub-user granted one or more in-scope services.","tags":["Users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}":{"get":{"summary":"One sub-user with its per-product rows.","tags":["Users"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a sub-user and release its credentials.","tags":["Users"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}/password":{"post":{"summary":"Reset the sub-user's proxy password for a product.","tags":["Users"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}/enable":{"post":{"summary":"Enable a sub-user's access to a product.","tags":["Users"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}/disable":{"post":{"summary":"Disable a sub-user's access to a product.","tags":["Users"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}/allocation":{"patch":{"summary":"Set a sub-user's traffic allocation.","tags":["Users"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}/endpoints":{"get":{"summary":"Generate proxy configuration for a sub-user.","tags":["Endpoints"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"protocol","in":"query","schema":{"type":"string","enum":["http","https","socks5"]}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"session_id","in":"query","schema":{"type":"string"}},{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}/endpoints/rotate":{"post":{"summary":"Regenerate configuration with fresh session ids.","tags":["Endpoints"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"protocol","in":"query","schema":{"type":"string","enum":["http","https","socks5"]}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"session_id","in":"query","schema":{"type":"string"}},{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/proxy-check":{"post":{"summary":"Check an endpoint's connectivity and exit IP.","tags":["Endpoints"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage/overview":{"get":{"summary":"Balance and usage per in-scope product.","tags":["Usage"],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage/traffic":{"get":{"summary":"Period traffic bytes for one product.","tags":["Usage"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"start_at","in":"query","schema":{"type":"string"}},{"name":"end_at","in":"query","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["hour","day","week","auto"]}},{"name":"status","in":"query","schema":{"type":"integer"}},{"name":"status_not","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage/traffic/history":{"get":{"summary":"Traffic time series for one product.","tags":["Usage"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"start_at","in":"query","schema":{"type":"string"}},{"name":"end_at","in":"query","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["hour","day","week","auto"]}},{"name":"status","in":"query","schema":{"type":"integer"}},{"name":"status_not","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage/requests/history":{"get":{"summary":"Request-count time series for one product.","tags":["Usage"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"start_at","in":"query","schema":{"type":"string"}},{"name":"end_at","in":"query","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["hour","day","week","auto"]}},{"name":"status","in":"query","schema":{"type":"integer"}},{"name":"status_not","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage/breakdown":{"get":{"summary":"Share of traffic by sub-user and by country.","tags":["Usage"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"start_at","in":"query","schema":{"type":"string"}},{"name":"end_at","in":"query","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["hour","day","week","auto"]}},{"name":"status","in":"query","schema":{"type":"integer"}},{"name":"status_not","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage/users":{"get":{"summary":"Per-sub-user traffic for the period.","tags":["Usage"],"parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"},"description":"Product key, e.g. `residential` or `mobile`. Must be in the token's scope."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Supplier key. Optional when the token is scoped to a single supplier for the product; required when several."},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"start_at","in":"query","schema":{"type":"string"}},{"name":"end_at","in":"query","schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["hour","day","week","auto"]}},{"name":"status","in":"query","schema":{"type":"integer"}},{"name":"status_not","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}