{ "openapi": "3.0.3", "info": { "title": "GIGABIT Partner API", "version": "1.0.0", "description": "API for mobile proxy integration: port orders and renewals, access management and billing.\n\nLong-running operations return HTTP 202 and a server-generated id. Status and results are available through GET /operations/{id}. Checking status does not create another operation." }, "servers": [ { "url": "https://api.gigabit.ltd/api/partner/v1" } ], "security": [ { "PartnerToken": [] } ], "tags": [ { "name": "operations", "description": "Operations" }, { "name": "funds", "description": "Balance & billing" }, { "name": "orders", "description": "Catalogue & orders" }, { "name": "access", "description": "Credentials & IP rotation" }, { "name": "profile", "description": "Partner profile" } ], "paths": { "/orders/{id}/rotation-token": { "post": { "operationId": "rotation-token", "tags": [ "access" ], "summary": "Reset IP rotation token", "description": "Creates a new IP rotation token and returns a ready-to-use URL. The previous token and all URLs containing it stop working immediately. The proxy password and timer remain unchanged.\n\nThe response is returned immediately, without a background operation. The new URL is also available in the port’s rotation_url field.", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "rotation_token": { "type": "string" }, "rotation_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "New link", "value": { "success": true, "data": { "rotation_token": "0123456789abcdef0123456789abcdef", "rotation_url": "https://api.gigabit.ltd/change_ip?token=0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Order ID from the id field in the port list." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "0": { "summary": "New link", "value": {} } } } } } } }, "/balance": { "get": { "operationId": "balance", "tags": [ "funds" ], "summary": "Balance", "description": "Current balance, credit limit, available funds, discount and partner prices.\n\n", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "currency": { "type": "string" }, "balance_cents": { "type": "integer" }, "reserved_cents": { "type": "integer" }, "credit_limit_cents": { "type": "integer" }, "debt_cents": { "type": "integer" }, "available_cents": { "type": "integer" }, "withdrawable_cents": { "type": "integer" }, "discount_percent": { "type": "integer" }, "prefix": { "type": "string" }, "api_token_hint": { "type": "string" }, "monthly_net_cents": { "type": "integer" }, "payment_method": { "type": "string" }, "connection_domains": { "type": "object", "properties": { "host": { "type": "string" }, "api": { "type": "string" } } }, "paid_in_cents": { "type": "integer" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "base_net_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "vat_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "tax_at_topup": { "type": "boolean" }, "discount_percent": { "type": "integer" }, "months": { "type": "integer" }, "days": { "type": "integer" }, "pricing_version": { "type": "integer" }, "tax": { "type": "object", "properties": { "mode": { "type": "string" }, "rate_percent": { "type": "integer" }, "vat_code": { "type": "string" }, "reverse_charge": { "type": "boolean" } } } } } }, "topup_tax": { "type": "object", "properties": { "mode": { "type": "string" }, "rate_percent": { "type": "integer" }, "vat_code": { "type": "string" }, "reverse_charge": { "type": "boolean" } } }, "can_order_new_ports": { "type": "boolean" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Balance", "value": { "success": true, "data": { "currency": "EUR", "balance_cents": 10000, "reserved_cents": 0, "credit_limit_cents": 10000, "debt_cents": 0, "available_cents": 20000, "withdrawable_cents": 10000, "discount_percent": 10, "prefix": "astra", "api_token_hint": "demo12", "monthly_net_cents": 4500, "payment_method": "card", "connection_domains": { "host": "", "api": "" }, "paid_in_cents": 10000, "prices": [ { "currency": "EUR", "base_net_cents": 4500, "net_cents": 4050, "vat_cents": 0, "total_cents": 4050, "tax_at_topup": true, "discount_percent": 10, "months": 1, "days": 30, "pricing_version": 1, "tax": { "mode": "vat", "rate_percent": 23, "vat_code": "23", "reverse_charge": false } } ], "topup_tax": { "mode": "vat", "rate_percent": 23, "vat_code": "23", "reverse_charge": false }, "can_order_new_ports": true } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/catalog": { "get": { "operationId": "catalog", "tags": [ "orders" ], "summary": "Available ports", "description": "Available port numbers grouped by operator and location.\n\nAvailability is checked when placing an order. Viewing the catalogue does not reserve ports.", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "ports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" } } } }, "available": { "type": "integer" } } } }, "prices": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "base_net_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "vat_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "tax_at_topup": { "type": "boolean" }, "discount_percent": { "type": "integer" }, "months": { "type": "integer" }, "days": { "type": "integer" }, "pricing_version": { "type": "integer" }, "tax": { "type": "object", "properties": { "mode": { "type": "string" }, "rate_percent": { "type": "integer" }, "vat_code": { "type": "string" }, "reverse_charge": { "type": "boolean" } } } } } } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Availability", "value": { "success": true, "data": { "items": [ { "operator": { "id": "operator-orange", "name": "Orange" }, "location": { "id": "location-warsaw", "name": "Warsaw" }, "ports": [ { "id": "b1c2d3e4f5a60123456789abcdef0123", "number": 10001 }, { "id": "b2c3d4e5f6a70123456789abcdef0123", "number": 10002 } ], "available": 2 } ], "prices": [ { "currency": "EUR", "base_net_cents": 4500, "net_cents": 4050, "vat_cents": 0, "total_cents": 4050, "tax_at_topup": true, "discount_percent": 10, "months": 1, "days": 30, "pricing_version": 1, "tax": { "mode": "vat", "rate_percent": 23, "vat_code": "23", "reverse_charge": false } } ] } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "post": { "operationId": "create-order", "tags": [ "orders" ], "summary": "Port order", "description": "Orders one available port for 30 days using its catalogue number or ID. The cost is debited from the balance.\n\nLong-running operations return HTTP 202 and a server-generated id. Status and results are available through GET /operations/{id}. Checking status does not create another operation.", "responses": { "202": { "description": "Example response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] } ] }, "examples": { "0": { "summary": "By number", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } }, "1": { "summary": "By ID", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "port_number": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Port number from the catalogue. Exactly one of port_number or port_id is required." }, "port_id": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Port ID from the catalogue, instead of port_number." } }, "additionalProperties": false, "oneOf": [ { "required": [ "port_number" ] }, { "required": [ "port_id" ] } ] }, "examples": { "0": { "summary": "By number", "value": { "port_number": 10001 } }, "1": { "summary": "By ID", "value": { "port_id": "b1c2d3e4f5a60123456789abcdef0123" } } } } } } }, "get": { "operationId": "orders", "tags": [ "orders" ], "summary": "Port list", "description": "Current account ports: rental expiry, connection details, IP and automatic IP rotation.\n\nTo change the IP, send a GET request to the full rotation_url returned in the port details. No Authorization header is required. The URL already contains the port token.", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "port_id": { "type": "string" }, "number": { "type": "integer" }, "host": { "type": "string" }, "username": { "type": "string" }, "proxy_password": { "type": "string" }, "status": { "type": "string" }, "expires": { "type": "string" }, "operator": { "type": "string" }, "cityName": { "type": "string" }, "ip": { "type": "string" }, "rotation_url": { "type": "string" }, "rotation": { "type": "boolean" }, "rotation_seconds": { "type": "integer" }, "connection_options": { "type": "object", "properties": { "custom": { "type": "object", "properties": { "host": { "type": "string" }, "rotation_url": { "type": "string" } } } } } } } } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Ports", "value": { "success": true, "data": { "items": [ { "id": "a1b2c3d4e5f60123456789abcdef0123", "port_id": "b1c2d3e4f5a60123456789abcdef0123", "number": 10001, "host": "l1.gigabit.ltd", "username": "astra_a1b2c3d4e5f", "proxy_password": "EXAMPLE_ONLY_22_CHARS_x", "status": "active", "expires": "2026-12-09T22:59:59+00:00", "operator": "Orange", "cityName": "Warsaw", "ip": "198.51.100.42", "rotation_url": "https://api.gigabit.ltd/change_ip?token=EXAMPLE_ROTATION_TOKEN_REPLACE_ME", "rotation": true, "rotation_seconds": 120, "connection_options": { "custom": { "host": "proxy.example.com", "rotation_url": "https://api.example.com/change_ip?token=EXAMPLE_ROTATION_TOKEN_REPLACE_ME" } } } ] } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/operations/{id}": { "get": { "operationId": "operation-status", "tags": [ "operations" ], "summary": "Operation status", "description": "Returns the account operation’s status and result. A quick check without repeating the action.\n\n", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "order_ids": { "type": "array", "items": { "type": "string" } }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "price": { "type": "object", "properties": { "currency": { "type": "string" }, "base_net_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "vat_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "tax_at_topup": { "type": "boolean" }, "discount_percent": { "type": "integer" }, "months": { "type": "integer" }, "days": { "type": "integer" }, "pricing_version": { "type": "integer" }, "tax": { "type": "object", "properties": { "mode": { "type": "string" }, "rate_percent": { "type": "integer" }, "vat_code": { "type": "string" }, "reverse_charge": { "type": "boolean" } } } } } } }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string" }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] } ] }, "examples": { "0": { "summary": "Queued", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } }, "1": { "summary": "Completed", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "ready", "error": null, "result": { "id": "partner_0123456789abcdef0123456789abcdef", "state": "ready", "error": null, "order_ids": [ "a1b2c3d4e5f60123456789abcdef0123" ], "amount_cents": 4050, "currency": "EUR", "price": { "currency": "EUR", "base_net_cents": 4500, "net_cents": 4050, "vat_cents": 0, "total_cents": 4050, "tax_at_topup": true, "discount_percent": 10, "months": 1, "days": 30, "pricing_version": 1, "tax": { "mode": "vat", "rate_percent": 23, "vat_code": "23", "reverse_charge": false } } }, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } }, "2": { "summary": "Failed", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "failed", "error": "insufficient_partner_balance", "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Operation ID returned in the HTTP 202 response." } } ] } }, "/orders/{id}": { "get": { "operationId": "order", "tags": [ "orders" ], "summary": "Port details", "description": "Details of an order belonging to the account. Unavailable or missing orders return 404.\n\nTo change the IP, send a GET request to the full rotation_url returned in the port details. No Authorization header is required. The URL already contains the port token.", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "port_id": { "type": "string" }, "number": { "type": "integer" }, "host": { "type": "string" }, "username": { "type": "string" }, "proxy_password": { "type": "string" }, "status": { "type": "string" }, "expires": { "type": "string" }, "operator": { "type": "string" }, "cityName": { "type": "string" }, "ip": { "type": "string" }, "rotation_url": { "type": "string" }, "rotation": { "type": "boolean" }, "rotation_seconds": { "type": "integer" }, "connection_options": { "type": "object", "properties": { "custom": { "type": "object", "properties": { "host": { "type": "string" }, "rotation_url": { "type": "string" } } } } } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Port", "value": { "success": true, "data": { "id": "a1b2c3d4e5f60123456789abcdef0123", "port_id": "b1c2d3e4f5a60123456789abcdef0123", "number": 10001, "host": "l1.gigabit.ltd", "username": "astra_a1b2c3d4e5f", "proxy_password": "EXAMPLE_ONLY_22_CHARS_x", "status": "active", "expires": "2026-12-09T22:59:59+00:00", "operator": "Orange", "cityName": "Warsaw", "ip": "198.51.100.42", "rotation_url": "https://api.gigabit.ltd/change_ip?token=EXAMPLE_ROTATION_TOKEN_REPLACE_ME", "rotation": true, "rotation_seconds": 120, "connection_options": { "custom": { "host": "proxy.example.com", "rotation_url": "https://api.example.com/change_ip?token=EXAMPLE_ROTATION_TOKEN_REPLACE_ME" } } } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Order ID (id) or port ID (port_id) from the port list." } } ] } }, "/orders/{id}/renew": { "post": { "operationId": "renew", "tags": [ "orders" ], "summary": "Port renewal", "description": "Extends one port rental by 30 days, paid from the balance. Only the port number or ID in the URL is required.\n\nLong-running operations return HTTP 202 and a server-generated id. Status and results are available through GET /operations/{id}. Checking status does not create another operation.", "responses": { "202": { "description": "Example response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] } ] }, "examples": { "0": { "summary": "By number", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } }, "1": { "summary": "By ID", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Port number or port ID. The order id from GET /orders is also accepted." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "0": { "summary": "By number", "value": {} }, "1": { "summary": "By ID", "value": {} } } } } } } }, "/orders/{id}/password": { "post": { "operationId": "password", "tags": [ "access" ], "summary": "Credential change by ID", "description": "The server generates a new password. With change_login=true it also generates a login using the current partner prefix. Available only for active rentals.\n\nNew credentials are available in result after application. operation_superseded means a newer command changed the credentials.", "responses": { "202": { "description": "Example response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] } ] }, "examples": { "0": { "summary": "Login and password", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } }, "1": { "summary": "Password only", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Order ID (id) or port ID (port_id) from the port list." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_login": { "type": "boolean", "default": false, "description": "true generates a new login with the current prefix and a new password. false changes the password only. Legacy shared credentials become a separate pair even without this flag." } }, "additionalProperties": false }, "examples": { "0": { "summary": "Login and password", "value": { "change_login": true } }, "1": { "summary": "Password only", "value": { "change_login": false } } } } } } } }, "/orders/{id}/rotation": { "get": { "operationId": "rotation-get", "tags": [ "access" ], "summary": "IP rotation timer", "description": "Current timer state. When rotation=true, rotation_seconds is included. When disabled, only rotation=false is returned.\n\n", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "rotation": { "type": "boolean" }, "rotation_seconds": { "type": "integer" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "rotation": { "type": "boolean" } } } }, "required": [ "success", "data" ] } ] }, "examples": { "0": { "summary": "Enabled", "value": { "success": true, "data": { "rotation": true, "rotation_seconds": 120 } } }, "1": { "summary": "Disabled", "value": { "success": true, "data": { "rotation": false } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Order ID (id) or port ID (port_id) from the port list." } } ] }, "put": { "operationId": "rotation-set", "tags": [ "access" ], "summary": "Timer settings", "description": "Enable the timer with rotation=true and rotation_seconds, an integer from 20 to 86400 seconds. Values below 20 return rotation_interval_too_short. To disable it, send only rotation=false.\n\nThe operation remains processing until the timer setting is confirmed.", "responses": { "202": { "description": "Example response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] } ] }, "examples": { "0": { "summary": "Every 120 seconds", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } }, "1": { "summary": "Disable", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Order ID (id) or port ID (port_id) from the port list." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rotation": { "type": "boolean", "description": "true enables the timer; false disables it." }, "rotation_seconds": { "type": "integer", "minimum": 20, "maximum": 86400, "description": "Required when rotation=true. Omit this field when rotation=false." } }, "additionalProperties": false, "required": [ "rotation" ], "oneOf": [ { "properties": { "rotation": { "enum": [ true ] } }, "required": [ "rotation_seconds" ] }, { "properties": { "rotation": { "enum": [ false ] } }, "not": { "required": [ "rotation_seconds" ] } } ] }, "examples": { "0": { "summary": "Every 120 seconds", "value": { "rotation": true, "rotation_seconds": 120 } }, "1": { "summary": "Disable", "value": { "rotation": false } } } } } } } }, "/topups": { "post": { "operationId": "topup", "tags": [ "funds" ], "summary": "Balance top-up", "description": "Creates a Stripe payment link. amount_cents is the balance credit in euro cents; total_cents is the payment total including applicable VAT.\n\n", "responses": { "202": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Card / Stripe", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 100, "maximum": 10000000, "description": "EUR 1-100,000, in integer euro cents." } }, "additionalProperties": false, "required": [ "amount_cents" ] }, "examples": { "0": { "summary": "Card / Stripe", "value": { "amount_cents": 10000 } } } } } } } }, "/topups/{id}": { "get": { "operationId": "topup-status", "tags": [ "funds" ], "summary": "Top-up status", "description": "Returns the account’s top-up status. paid confirms the balance has been credited. Returning from Stripe alone does not confirm payment.\n\nStates: creating, pending, paid, expired, failed.", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "url": { "type": "string" }, "amount_cents": { "type": "integer" }, "vat_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "currency": { "type": "string" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Stripe", "value": { "success": true, "data": { "id": "ptop_0123456789abcdef0123456789abcdef", "state": "pending", "url": "https://checkout.stripe.com/c/pay/EXAMPLE_SESSION", "amount_cents": 10000, "vat_cents": 2300, "total_cents": 12300, "currency": "EUR" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Top-up ID returned by POST /topups." } } ] } }, "/transactions": { "get": { "operationId": "transactions", "tags": [ "funds" ], "summary": "Transaction history", "description": "Operations newest first, with sources, comments, amounts and balances after each entry. Technical purchase reservations are hidden by default.\n\n", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "operation": { "type": "string" }, "amount_cents": { "type": "integer" }, "reserved_delta_cents": { "type": "integer" }, "source": { "type": "string" }, "comment": { "type": "string" }, "reference": { "type": "string" }, "balance_after_cents": { "type": "integer" }, "reserved_after_cents": { "type": "integer" }, "sequence": { "type": "integer" } } } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "First page", "value": { "success": true, "data": { "items": [ { "id": "ptop_0123456789abcdef0123456789abcdef:credit", "created_at": "2026-11-09T12:05:00+00:00", "currency": "EUR", "operation": "topup", "amount_cents": 10000, "reserved_delta_cents": 0, "source": "stripe", "comment": "", "reference": "ptop_0123456789abcdef0123456789abcdef", "balance_after_cents": 10000, "reserved_after_cents": 0, "sequence": 1 } ], "total": 1, "offset": 0, "limit": 30 } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of entries to skip." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30, "description": "Page size: 1-100." } }, { "name": "include_reservations", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ], "description": "1 includes purchase_reserve and purchase_release." } } ] } }, "/withdrawals": { "post": { "operationId": "withdrawal", "tags": [ "funds" ], "summary": "Withdrawal request", "description": "Creates a request and reserves the amount pending review. withdrawable_cents specifies the refundable amount; it excludes the credit limit and nonrefundable compensation.\n\nAfter the request is processed, result.state=requested means a decision is pending. The operation remains processing until payment is confirmed or the request is rejected.", "responses": { "202": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "error": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "status_url": { "type": "string" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Request", "value": { "success": true, "data": { "id": "op_0123456789abcdef0123456789abcdef", "state": "queued", "error": null, "result": null, "created_at": "2026-11-10T12:00:00+00:00", "status_url": "/api/partner/v1/operations/op_0123456789abcdef0123456789abcdef" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 100, "maximum": 100000000, "description": "EUR amount in cents, no more than the withdrawable funds." }, "comment": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Payment details or explanation. Must be nonempty after trimming." } }, "additionalProperties": false, "required": [ "amount_cents", "comment" ] }, "examples": { "0": { "summary": "Request", "value": { "amount_cents": 5000, "comment": "Please contact me to confirm payment details." } } } } } } } }, "/profile": { "put": { "operationId": "profile", "tags": [ "profile" ], "summary": "Login prefix", "description": "The prefix is the beginning of port logins, such as a brand name. Logins use the format prefix_random: with prefix=astra, a new port receives a login such as astra_a1b2c3d4e5f. The random suffix is generated separately for each port.\n\nChanging the prefix does not change existing logins. New ports and login changes using change_login=true use the current prefix. The prefix must be unique; a taken prefix returns 409 partner_prefix_taken.", "responses": { "200": { "description": "Example response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "prefix": { "type": "string" } } } }, "required": [ "success", "data" ] }, "examples": { "0": { "summary": "Prefix", "value": { "success": true, "data": { "prefix": "astra" } } } } } } }, "default": { "description": "Errors", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prefix": { "type": "string", "minLength": 2, "maxLength": 24, "pattern": "^[a-z][a-z0-9-]{1,23}$", "description": "2-24 characters: Latin letters, digits and hyphens, starting with a letter. Normalized to lowercase. proxy and gigabit are reserved." } }, "additionalProperties": false, "required": [ "prefix" ] }, "examples": { "0": { "summary": "Prefix", "value": { "prefix": "astra" } } } } } } } } }, "components": { "securitySchemes": { "PartnerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "gbp_…" } }, "schemas": { "Error": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retry_after": { "type": "integer" } } } } } }