Skip to content

Commit ae6dbd0

Browse files
mcowgermcowger
committed
docs(openapi): add missing management endpoint definitions
Add OpenAPI path definitions for 11 previously undocumented management endpoints: Config endpoints: - GET/PATCH /v0/management/config/background-exploration - GET/PATCH /v0/management/config/cooldown - GET/PATCH /v0/management/config/exploration-rate - GET/PATCH /v0/management/config/failover PI (Plexus Internal) endpoints: - GET /v0/management/pi/providers - GET /v0/management/pi/models Quota management endpoints: - GET /v0/management/quota-checkers - GET /v0/management/quotas/backup-legacy-snapshots - GET /v0/management/quotas/legacy-snapshot-status - POST /v0/management/quotas/migrate-legacy-snapshots - POST /v0/management/quotas/truncate-legacy-snapshots All endpoints include full request/response schemas, security requirements, and usage documentation. OpenAPI spec validates successfully.
1 parent 7a50be1 commit ae6dbd0

12 files changed

Lines changed: 897 additions & 0 deletions

‎docs/openapi/openapi.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -404,6 +404,14 @@ paths:
404404
$ref: paths/v0_management_config_export.yaml
405405
/v0/management/config/vision-fallthrough:
406406
$ref: paths/v0_management_config_vision-fallthrough.yaml
407+
/v0/management/config/background-exploration:
408+
$ref: paths/v0_management_config_background-exploration.yaml
409+
/v0/management/config/cooldown:
410+
$ref: paths/v0_management_config_cooldown.yaml
411+
/v0/management/config/exploration-rate:
412+
$ref: paths/v0_management_config_exploration-rate.yaml
413+
/v0/management/config/failover:
414+
$ref: paths/v0_management_config_failover.yaml
407415
/v0/management/system-settings:
408416
$ref: paths/v0_management_system-settings.yaml
409417
/v0/management/providers:
@@ -412,6 +420,10 @@ paths:
412420
$ref: paths/v0_management_providers_{slug}.yaml
413421
/v0/management/providers/fetch-models:
414422
$ref: paths/v0_management_providers_fetch-models.yaml
423+
/v0/management/pi/providers:
424+
$ref: paths/v0_management_pi_providers.yaml
425+
/v0/management/pi/models:
426+
$ref: paths/v0_management_pi_models.yaml
415427
/v0/management/aliases:
416428
$ref: paths/v0_management_aliases.yaml
417429
/v0/management/aliases/{slug}:
@@ -432,6 +444,16 @@ paths:
432444
$ref: paths/v0_management_mcp-servers_{serverName}.yaml
433445
/v0/management/quota-checker-types:
434446
$ref: paths/v0_management_quota-checker-types.yaml
447+
/v0/management/quota-checkers:
448+
$ref: paths/v0_management_quota-checkers.yaml
449+
/v0/management/quotas/backup-legacy-snapshots:
450+
$ref: paths/v0_management_quotas_backup-legacy-snapshots.yaml
451+
/v0/management/quotas/legacy-snapshot-status:
452+
$ref: paths/v0_management_quotas_legacy-snapshot-status.yaml
453+
/v0/management/quotas/migrate-legacy-snapshots:
454+
$ref: paths/v0_management_quotas_migrate-legacy-snapshots.yaml
455+
/v0/management/quotas/truncate-legacy-snapshots:
456+
$ref: paths/v0_management_quotas_truncate-legacy-snapshots.yaml
435457
/v0/management/usage:
436458
$ref: paths/v0_management_usage.yaml
437459
/v0/management/usage/summary:

‎docs/openapi/paths/v0_management_config_background-exploration.yaml‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
get:
2+
tags:
3+
- Management — Config
4+
summary: Get background exploration config (admin only)
5+
description: |
6+
Returns the background exploration configuration used by the
7+
`BackgroundExplorer` service for automatic performance probing.
8+
9+
## What's included
10+
11+
- `enabled` — Whether background exploration is active
12+
- `stalenessThresholdSeconds` — How old data can be before re-probing
13+
- `workerConcurrency` — Number of parallel probe workers (1-16)
14+
15+
## Use case
16+
17+
Background exploration automatically refreshes performance data for
18+
model aliases by sending probe requests. This endpoint returns the
19+
current configuration for that system.
20+
21+
**Admin only** — limited principals receive 403.
22+
security:
23+
- AdminKey: []
24+
responses:
25+
'200':
26+
description: Background exploration config.
27+
content:
28+
application/json:
29+
schema:
30+
type: object
31+
properties:
32+
enabled:
33+
type: boolean
34+
description: Whether background exploration is enabled
35+
stalenessThresholdSeconds:
36+
type: integer
37+
description: Seconds before data is considered stale
38+
workerConcurrency:
39+
type: integer
40+
minimum: 1
41+
maximum: 16
42+
description: Number of parallel probe workers
43+
'401':
44+
description: Authentication required or invalid credentials.
45+
operationId: getV0ManagementConfigBackgroundExploration
46+
patch:
47+
tags:
48+
- Management — Config
49+
summary: Update background exploration config (admin only)
50+
description: |
51+
Partially updates the background exploration configuration. Only
52+
provided fields are updated; others retain their current values.
53+
54+
## Validation rules
55+
56+
- `enabled` — Must be a boolean
57+
- `stalenessThresholdSeconds` — Integer >= 1
58+
- `workerConcurrency` — Integer between 1 and 16
59+
60+
**Admin only** — limited principals receive 403.
61+
security:
62+
- AdminKey: []
63+
requestBody:
64+
required: true
65+
content:
66+
application/json:
67+
schema:
68+
type: object
69+
properties:
70+
enabled:
71+
type: boolean
72+
description: Enable or disable background exploration
73+
stalenessThresholdSeconds:
74+
type: integer
75+
minimum: 1
76+
description: Seconds before data is considered stale
77+
workerConcurrency:
78+
type: integer
79+
minimum: 1
80+
maximum: 16
81+
description: Number of parallel probe workers
82+
examples:
83+
enable_exploration:
84+
summary: Enable with default thresholds
85+
value:
86+
enabled: true
87+
adjust_workers:
88+
summary: Increase worker concurrency
89+
value:
90+
workerConcurrency: 8
91+
custom_threshold:
92+
summary: Custom staleness threshold
93+
value:
94+
stalenessThresholdSeconds: 3600
95+
responses:
96+
'200':
97+
description: Updated config.
98+
content:
99+
application/json:
100+
schema:
101+
type: object
102+
properties:
103+
enabled:
104+
type: boolean
105+
stalenessThresholdSeconds:
106+
type: integer
107+
workerConcurrency:
108+
type: integer
109+
'400':
110+
description: Invalid request body or validation failed.
111+
'401':
112+
description: Authentication required or invalid credentials.
113+
operationId: patchV0ManagementConfigBackgroundExploration

‎docs/openapi/paths/v0_management_config_cooldown.yaml‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
get:
2+
tags:
3+
- Management — Config
4+
summary: Get cooldown policy config (admin only)
5+
description: |
6+
Returns the cooldown policy configuration used when providers
7+
experience errors or rate limiting.
8+
9+
## What's included
10+
11+
- `initialMinutes` — Initial cooldown duration after first error
12+
- `maxMinutes` — Maximum cooldown duration after repeated errors
13+
14+
## How cooldowns work
15+
16+
When a provider fails, Plexus applies an exponential backoff cooldown:
17+
1. First error: `initialMinutes` cooldown
18+
2. Repeated errors: Cooldown doubles each time
19+
3. Cap: Never exceeds `maxMinutes`
20+
21+
**Admin only** — limited principals receive 403.
22+
security:
23+
- AdminKey: []
24+
responses:
25+
'200':
26+
description: Cooldown policy config.
27+
content:
28+
application/json:
29+
schema:
30+
type: object
31+
properties:
32+
initialMinutes:
33+
type: number
34+
format: float
35+
minimum: 0.1
36+
description: Initial cooldown duration in minutes
37+
maxMinutes:
38+
type: number
39+
format: float
40+
minimum: 0.1
41+
description: Maximum cooldown duration in minutes
42+
'401':
43+
description: Authentication required or invalid credentials.
44+
operationId: getV0ManagementConfigCooldown
45+
patch:
46+
tags:
47+
- Management — Config
48+
summary: Update cooldown policy config (admin only)
49+
description: |
50+
Partially updates the cooldown policy configuration. Only provided
51+
fields are updated; others retain their current values.
52+
53+
## Validation rules
54+
55+
- `initialMinutes` — Must be >= 0.1 (6 seconds minimum)
56+
- `maxMinutes` — Must be >= 0.1 and >= `initialMinutes`
57+
58+
**Admin only** — limited principals receive 403.
59+
security:
60+
- AdminKey: []
61+
requestBody:
62+
required: true
63+
content:
64+
application/json:
65+
schema:
66+
type: object
67+
properties:
68+
initialMinutes:
69+
type: number
70+
format: float
71+
minimum: 0.1
72+
description: 'Initial cooldown duration in minutes (min: 0.1 = 6 seconds)'
73+
maxMinutes:
74+
type: number
75+
format: float
76+
minimum: 0.1
77+
description: Maximum cooldown duration in minutes
78+
examples:
79+
aggressive:
80+
summary: Aggressive retry (short cooldowns)
81+
value:
82+
initialMinutes: 0.5
83+
maxMinutes: 5
84+
conservative:
85+
summary: Conservative retry (long cooldowns)
86+
value:
87+
initialMinutes: 2
88+
maxMinutes: 30
89+
responses:
90+
'200':
91+
description: Updated cooldown policy.
92+
content:
93+
application/json:
94+
schema:
95+
type: object
96+
properties:
97+
initialMinutes:
98+
type: number
99+
format: float
100+
maxMinutes:
101+
type: number
102+
format: float
103+
'400':
104+
description: Invalid request body or validation failed.
105+
'401':
106+
description: Authentication required or invalid credentials.
107+
operationId: patchV0ManagementConfigCooldown

0 commit comments

Comments
 (0)