Restore unmodified Swagger UI presentation

Expand API reference and repair Swagger theme
2026-08-14 11:51:52 +00:00 · 2026-08-14 11:39:23 +00:00
3 changed files with 120 additions and 29 deletions
@@ -49,6 +49,10 @@ organisation UUID and needs `geofeeds:read` or `geofeeds:write`.
 - [`openapi/openapi.yaml`](openapi/openapi.yaml) is the source of truth.
 - Interactive reference: <https://as213905.com/docs/api/reference>
 - Machine-readable production contract: <https://as213905.com/api/v1/openapi.json>
 - Getting started: <https://as213905.com/docs/api/getting-started>
 - Authentication and scopes: <https://as213905.com/docs/api/authentication>
 - Complete endpoint examples: <https://as213905.com/docs/api/endpoints>
 - SDK guides: <https://as213905.com/docs/api/sdks>
 ## Development
@@ -3,22 +3,13 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="color-scheme" content="dark light" />
+    <title>AS213905 API — Swagger UI</title>
    <title>AS213905 API reference</title>
    <link rel="stylesheet" href="/docs/api/reference/assets/swagger-ui.css" />
    <link rel="icon" type="image/png" href="data:image/png;base64,iVBORw0KGgo=" />
    <style>
      html { box-sizing: border-box; overflow-y: scroll; }
      *, *::before, *::after { box-sizing: inherit; }
-      body { margin: 0; background: #201d21; }
+      body { margin: 0; background: #fafafa; }
      .swagger-ui .topbar { background: #171518; border-bottom: 1px solid #4a454b; }
      .swagger-ui .topbar-wrapper img { display: none; }
      .swagger-ui .topbar-wrapper::before { content: "AS213905 API"; color: #ffbe5c; font: 600 18px system-ui; }
      .swagger-ui .scheme-container { background: #29252a; box-shadow: none; }
      @media (max-width: 640px) {
        .swagger-ui .wrapper { padding: 0 12px; }
        .swagger-ui .opblock .opblock-summary { flex-wrap: wrap; }
        .swagger-ui .opblock-summary-path { max-width: 100%; font-size: 13px; }
      }
    </style>
  </head>
  <body>
@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
  title: AS213905 API
-  version: 1.1.0
+  version: 1.2.0
  description: |
    Customer automation API for organisations, invoices, services, traffic,
    tunnels and RFC 8805 geofeeds. Create a scoped key in Panel → Settings.
@@ -34,6 +34,7 @@ paths:
    get:
      tags: [Organisation]
      summary: Get the API key's organisation
      description: Returns the single organisation permanently bound to the bearer key. Requires `organizations:read`.
      operationId: getOrganization
      x-required-scope: organizations:read
      responses:
@@ -48,6 +49,7 @@ paths:
    get:
      tags: [Invoices]
      summary: List invoices, newest first
      description: Returns all billing documents for the key organisation, ordered from newest to oldest. Requires `invoices:read`.
      operationId: listInvoices
      x-required-scope: invoices:read
      responses:
@@ -66,6 +68,7 @@ paths:
    get:
      tags: [Services]
      summary: List services
      description: Returns every customer service and its lifecycle state. Requires `services:read`.
      operationId: listServices
      x-required-scope: services:read
      responses:
@@ -86,6 +89,7 @@ paths:
    get:
      tags: [Services]
      summary: Get one service
      description: Returns one service owned by the key organisation. A foreign identifier is reported as not found. Requires `services:read`.
      operationId: getService
      x-required-scope: services:read
      responses:
@@ -107,17 +111,22 @@ paths:
    get:
      tags: [Services]
      summary: Read a BGP VM metric series
      description: Reads a sampled metric series from a controllable BGP VM. Requires `services:read`.
      operationId: getServiceMetrics
      x-required-scope: services:read
      parameters:
        - name: target
          in: query
          description: Metric to read. Network values are returned as bytes per second; percentage and load values use their native units.
          example: net_tx
          schema:
            type: string
            enum: [cpu_load, mem_usage_percent, net_rx, net_tx, iops, df.root.used]
            default: cpu_load
        - name: range
          in: query
          description: Time window ending at the current time.
          example: 6h
          schema: {type: string, enum: [1h, 6h, 24h, 7d], default: 24h}
      responses:
        '200':
@@ -134,6 +143,7 @@ paths:
    post:
      tags: [Services]
      summary: Start, stop or restart a BGP VM
      description: Queues an asynchronous power command for a controllable BGP VM. Requires `services:write`.
      operationId: powerService
      x-required-scope: services:write
      requestBody:
@@ -144,7 +154,9 @@ paths:
              type: object
              required: [action]
              properties:
-                action: {type: string, enum: [start, stop, restart]}
+                action: {type: string, enum: [start, stop, restart], examples: [restart], description: Power transition to queue.}
            examples:
              restart: {value: {action: restart}}
      responses:
        '202':
          description: Command accepted
@@ -164,6 +176,7 @@ paths:
    get:
      tags: [Traffic]
      summary: Get organisation transit usage
      description: Returns transferred bytes and 95th-percentile traffic for either the last N days or an explicit UTC date interval. `days` is mutually exclusive with `from`/`to`. Requires `traffic:read`.
      operationId: getTraffic
      x-required-scope: traffic:read
      parameters:
@@ -183,6 +196,7 @@ paths:
    get:
      tags: [Tunnels]
      summary: List tunnels
      description: Returns all transit tunnels and their provisioning state. Requires `tunnels:read`.
      operationId: listTunnels
      x-required-scope: tunnels:read
      responses:
@@ -200,6 +214,7 @@ paths:
    post:
      tags: [Tunnels]
      summary: Request a transit tunnel
      description: Records a Frankfurt transit tunnel for asynchronous provisioning. Currently `fra` is the only available location. Requires `tunnels:write`.
      operationId: createTunnel
      x-required-scope: tunnels:write
      requestBody:
@@ -207,6 +222,10 @@ paths:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateTunnelRequest'}
            examples:
              frankfurt:
                summary: Frankfurt GRE tunnel
                value: {peer_endpoint: 203.0.113.10, location: fra, label: fra-primary, announce: true}
      responses:
        '202':
          description: Tunnel recorded for provisioning
@@ -226,6 +245,7 @@ paths:
    delete:
      tags: [Tunnels]
      summary: Remove a tunnel asynchronously
      description: Queues teardown and returns before router configuration has completed. Requires `tunnels:write`.
      operationId: deleteTunnel
      x-required-scope: tunnels:write
      responses:
@@ -243,6 +263,7 @@ paths:
    get:
      tags: [Traffic, Tunnels]
      summary: Get one tunnel's usage
      description: Returns transferred bytes and 95th-percentile traffic for one tunnel. `days` is mutually exclusive with `from`/`to`. Requires `traffic:read`.
      operationId: getTunnelTraffic
      x-required-scope: traffic:read
      parameters:
@@ -265,6 +286,7 @@ paths:
    get:
      tags: [Geofeeds]
      summary: List geofeeds
      description: Lists the organisation's public RFC 8805 feeds. Each organisation can own at most two. Requires `geofeeds:read`.
      operationId: listGeofeeds
      x-required-scope: geofeeds:read
      responses:
@@ -278,6 +300,7 @@ paths:
    post:
      tags: [Geofeeds]
      summary: Create a geofeed (maximum two per organisation)
      description: Creates an empty feed and an unguessable public CSV URL. Requires `geofeeds:write`.
      operationId: createGeofeed
      x-required-scope: geofeeds:write
      requestBody:
@@ -288,7 +311,9 @@ paths:
              type: object
              required: [name]
              properties:
-                name: {type: string, minLength: 1, maxLength: 100}
+                name: {type: string, minLength: 1, maxLength: 100, examples: [Customer prefixes], description: Human-readable display name.}
            examples:
              default: {value: {name: Customer prefixes}}
      responses:
        '201':
          description: Created
@@ -306,6 +331,7 @@ paths:
    get:
      tags: [Geofeeds]
      summary: Get a geofeed and its records
      description: Returns feed metadata and all current RFC 8805 records. Requires `geofeeds:read`.
      operationId: getGeofeed
      x-required-scope: geofeeds:read
      responses:
@@ -324,6 +350,7 @@ paths:
    patch:
      tags: [Geofeeds]
      summary: Rename a geofeed
      description: Changes only the display name; the public URL remains valid. Requires `geofeeds:write`.
      operationId: updateGeofeed
      x-required-scope: geofeeds:write
      requestBody:
@@ -334,7 +361,9 @@ paths:
              type: object
              required: [name]
              properties:
-                name: {type: string, minLength: 1, maxLength: 100}
+                name: {type: string, minLength: 1, maxLength: 100, examples: [Production geofeed], description: New display name.}
            examples:
              rename: {value: {name: Production geofeed}}
      responses:
        '200':
          description: Updated
@@ -348,6 +377,7 @@ paths:
    delete:
      tags: [Geofeeds]
      summary: Delete a geofeed
      description: Permanently deletes the feed, its records and public CSV URL. Requires `geofeeds:write`.
      operationId: deleteGeofeed
      x-required-scope: geofeeds:write
      responses:
@@ -366,6 +396,7 @@ paths:
    put:
      tags: [Geofeeds]
      summary: Atomically replace all RFC 8805 records
      description: Validates the complete array and replaces all records in one transaction. No partial update is committed. Requires `geofeeds:write`.
      operationId: replaceGeofeedRecords
      x-required-scope: geofeeds:write
      requestBody:
@@ -380,6 +411,11 @@ paths:
                  type: array
                  maxItems: 1000
                  items: {$ref: '#/components/schemas/GeofeedRecordInput'}
            examples:
              frankfurt:
                value:
                  records:
                    - {prefix: 203.0.113.0/24, country_code: DE, region_code: DE-HE, city: Frankfurt am Main, postal_code: '60311'}
      responses:
        '200':
          description: Saved
@@ -397,6 +433,7 @@ paths:
    post:
      tags: [Geofeeds]
      summary: Rotate the unguessable public CSV URL
      description: Invalidates the previous URL immediately and issues a new public slug. Requires `geofeeds:write`.
      operationId: rotateGeofeedUrl
      x-required-scope: geofeeds:write
      responses:
@@ -420,48 +457,83 @@ components:
      name: id
      in: path
      required: true
      description: UUID returned by the corresponding list endpoint.
      example: 38fce115-83e6-4122-a65a-9c70c9187794
      schema: {type: string, format: uuid}
    OrganizationId:
      name: X-Organization-ID
      in: header
      required: true
      description: Organisation UUID. An API key can only address its own organisation.
      example: 9f44e0e7-13d4-4af3-bc6e-76b91c93b752
      schema: {type: string, format: uuid}
    Days:
      name: days
      in: query
      description: Last N days; mutually exclusive with from/to.
-      schema: {type: integer, minimum: 1, maximum: 366}
+      example: 7
      schema: {type: integer, minimum: 1, maximum: 366, default: 7}
    From:
      name: from
      in: query
      description: First UTC calendar date in an explicit interval. Use together with `to`; mutually exclusive with `days`.
      example: '2026-08-01'
      schema: {type: string, format: date}
    To:
      name: to
      in: query
      description: Inclusive whole-day end.
      example: '2026-08-07'
      schema: {type: string, format: date}
  responses:
    BadRequest:
      description: Invalid request
-      content: {application/json: {schema: {$ref: '#/components/schemas/APIError'}}}
+      content:
        application/json:
          schema: {$ref: '#/components/schemas/APIError'}
          examples:
            invalid_parameter: {value: {error: invalid_parameter, message: "days cannot be combined with from/to"}}
    Unauthenticated:
      description: Missing, malformed, expired, revoked or unknown API key
-      content: {application/json: {schema: {$ref: '#/components/schemas/APIError'}}}
+      content:
        application/json:
          schema: {$ref: '#/components/schemas/APIError'}
          examples:
            missing: {value: {error: api_key_required, message: "Authorization header is required"}}
            invalid: {value: {error: api_key_invalid, message: "The API key is invalid or expired"}}
    Forbidden:
      description: Missing scope or disallowed source address
-      content: {application/json: {schema: {$ref: '#/components/schemas/APIError'}}}
+      content:
        application/json:
          schema: {$ref: '#/components/schemas/APIError'}
          examples:
            scope: {value: {error: scope_required, message: "This endpoint requires traffic:read", required_scope: traffic:read}}
            address: {value: {error: address_not_allowed, message: "The request source is not allowed"}}
    NotFound:
      description: Resource not found
-      content: {application/json: {schema: {$ref: '#/components/schemas/APIError'}}}
+      content:
        application/json:
          schema: {$ref: '#/components/schemas/APIError'}
          examples:
            resource: {value: {error: not_found, message: "Resource not found"}}
    Conflict:
      description: Resource limit or state conflict
-      content: {application/json: {schema: {$ref: '#/components/schemas/APIError'}}}
+      content:
        application/json:
          schema: {$ref: '#/components/schemas/APIError'}
          examples:
            limit: {value: {error: geofeed_limit_reached, message: "An organisation can have at most two geofeeds"}}
    RateLimited:
      description: Rate limit exceeded
      headers:
-        Retry-After: {schema: {type: integer}}
+        Retry-After:
-      content: {application/json: {schema: {$ref: '#/components/schemas/APIError'}}}
+          description: Seconds before another attempt should be made.
          schema: {type: integer, minimum: 1, examples: [30]}
      content:
        application/json:
          schema: {$ref: '#/components/schemas/APIError'}
          examples:
            limited: {value: {error: rate_limited, message: "Too many requests", retry_after: 30}}
  schemas:
    APIError:
      type: object
@@ -488,6 +560,8 @@ components:
        name: {type: string}
        status: {type: string}
        commit_kbps: {type: integer, format: int64}
      examples:
        - {id: 9f44e0e7-13d4-4af3-bc6e-76b91c93b752, asn: 213905, name: Example Networks GmbH, status: active, commit_kbps: 1000000}
    Invoice:
      type: object
      required: [id, number, status, currency, total_cents]
@@ -501,6 +575,8 @@ components:
        period_to: {type: [string, 'null'], format: date}
        issued_at: {type: [string, 'null'], format: date-time}
        due_at: {type: [string, 'null'], format: date-time}
      examples:
        - {id: c089452d-9127-48b6-a1b8-407f9691a658, number: INV-2026-0042, status: paid, currency: EUR, total_cents: 900, period_from: '2026-08-01', period_to: '2026-08-31', issued_at: '2026-08-01T09:00:00Z', due_at: '2026-08-08T09:00:00Z'}
    Service:
      type: object
      required: [id, kind, label, status, monthly_cents]
@@ -514,12 +590,16 @@ components:
        controllable: {type: boolean}
        location: {type: string}
        configuration: {type: object, additionalProperties: true}
      examples:
        - {id: 38fce115-83e6-4122-a65a-9c70c9187794, kind: bgp_vm, label: BGP Small, status: active, monthly_cents: 900, next_due_on: '2026-09-01', controllable: true, location: fra, configuration: {vcpu: 2, memory_gib: 4, disk_gib: 50}}
    MetricPoint:
      type: object
      required: [t]
      properties:
        t: {type: string, format: date-time}
        v: {type: number}
      examples:
        - {t: '2026-08-14T14:00:00Z', v: 42.7}
    MetricSeries:
      type: object
      required: [metric, target, range, points]
@@ -528,6 +608,8 @@ components:
        target: {type: string}
        range: {type: string}
        points: {type: array, items: {$ref: '#/components/schemas/MetricPoint'}}
      examples:
        - {metric: Network transmit, target: net_tx, range: 6h, points: [{t: '2026-08-14T14:00:00Z', v: 1250000}, {t: '2026-08-14T14:05:00Z', v: 1310000}]}
    Period:
      type: object
      required: [from, to, label]
@@ -535,6 +617,8 @@ components:
        from: {type: string, format: date-time}
        to: {type: string, format: date-time}
        label: {type: string}
      examples:
        - {from: '2026-08-01T00:00:00Z', to: '2026-08-08T00:00:00Z', label: 1–7 August 2026}
    Traffic:
      type: object
      required: [p95_kbps, total_bytes, total_gb, period]
@@ -545,6 +629,8 @@ components:
        total_bytes: {type: integer, format: int64}
        total_gb: {type: number}
        period: {$ref: '#/components/schemas/Period'}
      examples:
        - {p95_kbps: 428500, commit_kbps: 1000000, over_commit: false, total_bytes: 482901204887, total_gb: 449.74, period: {from: '2026-08-01T00:00:00Z', to: '2026-08-08T00:00:00Z', label: 1–7 August 2026}}
    Tunnel:
      type: object
      required: [id, status, location, peer_endpoint]
@@ -558,14 +644,18 @@ components:
        inner_v4: {type: string}
        inner_v6: {type: string}
        announce: {type: boolean}
      examples:
        - {id: a5247bdd-e2d0-4c25-a1e6-c84e290cbfa1, status: active, label: fra-primary, location: fra, peer_endpoint: 203.0.113.10, ifname: gre-customer-1, inner_v4: 169.254.10.2/30, inner_v6: 'fe80::2/64', announce: true}
    CreateTunnelRequest:
      type: object
      required: [peer_endpoint, location]
      properties:
-        peer_endpoint: {type: string, format: ip}
+        peer_endpoint: {type: string, format: ip, examples: [203.0.113.10], description: Public remote GRE endpoint.}
-        location: {type: string, examples: [fra]}
+        location: {type: string, enum: [fra], examples: [fra], description: Service location; currently Frankfurt only.}
-        label: {type: string, maxLength: 100}
+        label: {type: string, maxLength: 100, examples: [fra-primary], description: Optional customer-visible name.}
-        announce: {type: boolean, default: false}
+        announce: {type: boolean, default: false, examples: [true], description: Request route announcement after configuration.}
      examples:
        - {peer_endpoint: 203.0.113.10, location: fra, label: fra-primary, announce: true}
    TunnelTraffic:
      allOf:
        - {$ref: '#/components/schemas/Traffic'}
@@ -582,6 +672,8 @@ components:
        record_count: {type: integer, minimum: 0}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
      examples:
        - {id: 661e65fd-a498-4418-af2f-dbc8e4b24535, name: Production geofeed, slug: geo-Q4cW8sR1.csv, record_count: 1, created_at: '2026-08-14T10:00:00Z', updated_at: '2026-08-14T14:00:00Z'}
    GeofeedRecordInput:
      type: object
      required: [prefix, country_code]
@@ -590,7 +682,9 @@ components:
        country_code: {type: string, pattern: '^[A-Z]{2}$', examples: [DE]}
        region_code: {type: string, maxLength: 128, examples: [DE-HE]}
        city: {type: string, maxLength: 128, examples: [Frankfurt am Main]}
-        postal_code: {type: string, maxLength: 128}
+        postal_code: {type: string, maxLength: 128, examples: ['60311']}
      examples:
        - {prefix: 203.0.113.0/24, country_code: DE, region_code: DE-HE, city: Frankfurt am Main, postal_code: '60311'}
    GeofeedRecord:
      allOf:
        - {$ref: '#/components/schemas/GeofeedRecordInput'}
@@ -609,3 +703,5 @@ components:
      properties:
        geofeeds: {type: array, items: {$ref: '#/components/schemas/Geofeed'}}
        limit: {type: integer, const: 2}
      examples:
        - {geofeeds: [{id: 661e65fd-a498-4418-af2f-dbc8e4b24535, name: Production geofeed, slug: geo-Q4cW8sR1.csv, record_count: 1, created_at: '2026-08-14T10:00:00Z', updated_at: '2026-08-14T14:00:00Z'}], limit: 2}
Author	SHA1	Message	Date
AS213905 Engineering	2057b4d685	Restore unmodified Swagger UI presentation	2026-08-14 11:51:52 +00:00
AS213905 Engineering	dd05901571	Expand API reference and repair Swagger theme	2026-08-14 11:39:23 +00:00