@1claw/openapi-spec 0.61.38 → 0.61.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/openapi.json +944 -1
  2. package/openapi.yaml +471 -1
  3. package/package.json +1 -1
package/openapi.yaml CHANGED
@@ -2,7 +2,7 @@ openapi: 3.1.0
2
2
 
3
3
  info:
4
4
  title: 1Claw API
5
- version: "0.61.38"
5
+ version: "0.61.40"
6
6
  description: |
7
7
  Secure secret management for AI agents. Provides vaults, secrets,
8
8
  policy-based access control, agent identity, Intents API,
@@ -70,6 +70,8 @@ tags:
70
70
  description: Secret sharing links
71
71
  - name: Organization
72
72
  description: Org membership and roles
73
+ - name: Spend
74
+ description: AI spend — inference cost per agent, provider and model, against budgets and caps
73
75
  - name: Billing
74
76
  description: Subscriptions, credits, and usage
75
77
  - name: Audit
@@ -4282,6 +4284,172 @@ paths:
4282
4284
  # Organization
4283
4285
  # ---------------------------------------------------------------------------
4284
4286
 
4287
+ /v1/spend/ai:
4288
+ get:
4289
+ tags: [Spend]
4290
+ summary: AI spend
4291
+ operationId: getAiSpend
4292
+ description: |
4293
+ Inference spend for the org over a window (default the last 30 days):
4294
+ totals with the previous equal-length window for comparison, a time series
4295
+ by provider, and breakdowns by provider, by model and by agent — each agent
4296
+ with its `shroud_config` daily budget, today's spend against it and the
4297
+ requests Shroud blocked for budget. `limits` carries router-key spend caps,
4298
+ the credit balance and 1Claw's inspection fees for the window (a separate
4299
+ number from provider cost). Every request is priced at ingest from the
4300
+ price card (`GET /v1/spend/ai/prices`); a request whose provider has no
4301
+ card is counted as unpriced, not free. Human and platform callers only.
4302
+ Backs the dashboard's Spend tab; the same numbers reach an org's own
4303
+ collector as OTEL metrics `ai.cost_usd`, `ai.tokens.input`, `ai.tokens.output`.
4304
+ parameters:
4305
+ - name: from
4306
+ in: query
4307
+ schema: { type: string, format: date-time }
4308
+ - name: to
4309
+ in: query
4310
+ schema: { type: string, format: date-time }
4311
+ - name: interval
4312
+ in: query
4313
+ schema: { type: string, enum: [day, week, month], default: day }
4314
+ - name: agent_id
4315
+ in: query
4316
+ schema: { type: string, format: uuid }
4317
+ - name: provider
4318
+ in: query
4319
+ schema: { type: string }
4320
+ responses:
4321
+ "200":
4322
+ description: Spend
4323
+ content:
4324
+ application/json:
4325
+ schema:
4326
+ $ref: "#/components/schemas/AiSpend"
4327
+ "400":
4328
+ $ref: "#/components/responses/BadRequest"
4329
+ "401":
4330
+ $ref: "#/components/responses/Unauthorized"
4331
+ "403":
4332
+ $ref: "#/components/responses/Forbidden"
4333
+
4334
+ /v1/spend/ai/export.csv:
4335
+ get:
4336
+ tags: [Spend]
4337
+ summary: AI spend as CSV
4338
+ operationId: exportAiSpendCsv
4339
+ description: One row per agent × provider × model in the window (same filters as `GET /v1/spend/ai`).
4340
+ parameters:
4341
+ - name: from
4342
+ in: query
4343
+ schema: { type: string, format: date-time }
4344
+ - name: to
4345
+ in: query
4346
+ schema: { type: string, format: date-time }
4347
+ - name: agent_id
4348
+ in: query
4349
+ schema: { type: string, format: uuid }
4350
+ - name: provider
4351
+ in: query
4352
+ schema: { type: string }
4353
+ responses:
4354
+ "200":
4355
+ description: CSV
4356
+ content:
4357
+ text/csv:
4358
+ schema: { type: string }
4359
+ "401":
4360
+ $ref: "#/components/responses/Unauthorized"
4361
+ "403":
4362
+ $ref: "#/components/responses/Forbidden"
4363
+
4364
+ /v1/spend/ai/prices:
4365
+ get:
4366
+ tags: [Spend]
4367
+ summary: LLM price card
4368
+ operationId: listLlmPrices
4369
+ description: |
4370
+ The global price card (public list prices per million tokens) plus this
4371
+ org's overrides. Matching: an org row beats a global row; among those the
4372
+ longest `model_pattern` wins; a pattern ending in `%` is a prefix match.
4373
+ responses:
4374
+ "200":
4375
+ description: Prices
4376
+ content:
4377
+ application/json:
4378
+ schema:
4379
+ type: object
4380
+ required: [prices]
4381
+ properties:
4382
+ prices:
4383
+ type: array
4384
+ items:
4385
+ $ref: "#/components/schemas/LlmModelPrice"
4386
+ "401":
4387
+ $ref: "#/components/responses/Unauthorized"
4388
+ put:
4389
+ tags: [Spend]
4390
+ summary: Set an org price override
4391
+ operationId: upsertLlmPrice
4392
+ description: Owner/admin. Upserts one override for this org; future requests are priced with it (history is not rewritten).
4393
+ requestBody:
4394
+ required: true
4395
+ content:
4396
+ application/json:
4397
+ schema:
4398
+ type: object
4399
+ required: [provider, model_pattern, input_usd_per_mtok, output_usd_per_mtok]
4400
+ properties:
4401
+ provider: { type: string, example: anthropic }
4402
+ model_pattern: { type: string, example: "claude-sonnet-5%" }
4403
+ input_usd_per_mtok: { type: number, example: 3 }
4404
+ output_usd_per_mtok: { type: number, example: 15 }
4405
+ responses:
4406
+ "200":
4407
+ description: The override
4408
+ content:
4409
+ application/json:
4410
+ schema:
4411
+ $ref: "#/components/schemas/LlmModelPrice"
4412
+ "400":
4413
+ $ref: "#/components/responses/BadRequest"
4414
+ "403":
4415
+ $ref: "#/components/responses/Forbidden"
4416
+
4417
+ /v1/spend/ai/prices/{id}:
4418
+ delete:
4419
+ tags: [Spend]
4420
+ summary: Remove an org price override
4421
+ operationId: deleteLlmPrice
4422
+ parameters:
4423
+ - name: id
4424
+ in: path
4425
+ required: true
4426
+ schema: { type: string, format: uuid }
4427
+ responses:
4428
+ "204":
4429
+ description: Removed
4430
+ "403":
4431
+ $ref: "#/components/responses/Forbidden"
4432
+ "404":
4433
+ $ref: "#/components/responses/NotFound"
4434
+
4435
+ /v1/spend/ai/reprice:
4436
+ post:
4437
+ tags: [Spend]
4438
+ summary: Price the org's unpriced requests
4439
+ operationId: repriceAiSpend
4440
+ description: Owner/admin. Re-runs the price card over rows that had no price when they arrived (after adding a card for that provider). Already-priced rows are untouched.
4441
+ responses:
4442
+ "200":
4443
+ description: Count
4444
+ content:
4445
+ application/json:
4446
+ schema:
4447
+ type: object
4448
+ properties:
4449
+ repriced: { type: integer }
4450
+ "403":
4451
+ $ref: "#/components/responses/Forbidden"
4452
+
4285
4453
  /v1/org/overview:
4286
4454
  get:
4287
4455
  tags: [Organization]
@@ -18985,6 +19153,173 @@ paths:
18985
19153
  description: Forbidden, or the plan does not include this
18986
19154
  '404':
18987
19155
  description: Not found
19156
+ /v1/runtimes/provision:
19157
+ post:
19158
+ tags: [Runtimes]
19159
+ summary: Provision an agent and its runtime in one call
19160
+ operationId: provisionRuntime
19161
+ description: |
19162
+ Creates (or reuses) the agent, its keys and default-vault grant, the runtime, and
19163
+ starts it. Each step runs the same code as the individual endpoints, so the
19164
+ `agent.create` consensus gate, plan caps, image allowlist and included-slot logic
19165
+ apply exactly as one click at a time. Human-only. The new agent's API key is
19166
+ returned once.
19167
+ requestBody:
19168
+ required: true
19169
+ content:
19170
+ application/json:
19171
+ schema:
19172
+ type: object
19173
+ required: [name, agent]
19174
+ properties:
19175
+ name:
19176
+ type: string
19177
+ template:
19178
+ type: string
19179
+ preset:
19180
+ type: string
19181
+ default: small
19182
+ agent:
19183
+ type: object
19184
+ description: Either `id` (existing) or `name` (create).
19185
+ properties:
19186
+ id:
19187
+ type: string
19188
+ format: uuid
19189
+ name:
19190
+ type: string
19191
+ description:
19192
+ type: string
19193
+ env_public:
19194
+ type: object
19195
+ additionalProperties:
19196
+ type: string
19197
+ expose_http:
19198
+ type: boolean
19199
+ source_repo:
19200
+ type: string
19201
+ startup_command:
19202
+ type: string
19203
+ environment:
19204
+ type: string
19205
+ start:
19206
+ type: boolean
19207
+ default: true
19208
+ approval_id:
19209
+ type: string
19210
+ format: uuid
19211
+ responses:
19212
+ "201":
19213
+ description: Provisioned
19214
+ content:
19215
+ application/json:
19216
+ schema:
19217
+ type: object
19218
+ required: [runtime, agent_id, started]
19219
+ properties:
19220
+ runtime:
19221
+ $ref: "#/components/schemas/RuntimeResponse"
19222
+ agent_id:
19223
+ type: string
19224
+ format: uuid
19225
+ agent_api_key:
19226
+ type: string
19227
+ description: Only when the agent was created here; shown once.
19228
+ vault_id:
19229
+ type: string
19230
+ format: uuid
19231
+ started:
19232
+ type: boolean
19233
+ "400":
19234
+ $ref: "#/components/responses/BadRequest"
19235
+ "401":
19236
+ $ref: "#/components/responses/Unauthorized"
19237
+ "403":
19238
+ $ref: "#/components/responses/Forbidden"
19239
+
19240
+ /v1/runtimes/{runtime_id}/env/resolved:
19241
+ get:
19242
+ tags: [Runtimes]
19243
+ summary: The environment the container is started with
19244
+ operationId: getRuntimeResolvedEnv
19245
+ description: |
19246
+ Every variable, its source (`platform`, `env_public`, `vault_env`, `agent`,
19247
+ `secret`) and which wins on a name collision. Vault-derived values and the minted
19248
+ agent token are named, never shown. Human-only; nothing is minted.
19249
+ parameters:
19250
+ - name: runtime_id
19251
+ in: path
19252
+ required: true
19253
+ schema:
19254
+ type: string
19255
+ format: uuid
19256
+ responses:
19257
+ "200":
19258
+ description: Resolved environment
19259
+ content:
19260
+ application/json:
19261
+ schema:
19262
+ type: object
19263
+ properties:
19264
+ runtime_id:
19265
+ type: string
19266
+ format: uuid
19267
+ environment:
19268
+ type: string
19269
+ restart_required_for_changes:
19270
+ type: boolean
19271
+ entries:
19272
+ type: array
19273
+ items:
19274
+ type: object
19275
+ properties:
19276
+ key:
19277
+ type: string
19278
+ source:
19279
+ type: string
19280
+ enum: [platform, env_public, vault_env, agent, secret]
19281
+ value:
19282
+ type: string
19283
+ masked:
19284
+ type: boolean
19285
+ overrides:
19286
+ type: string
19287
+ nullable: true
19288
+ "401":
19289
+ $ref: "#/components/responses/Unauthorized"
19290
+ "404":
19291
+ $ref: "#/components/responses/NotFound"
19292
+
19293
+ /v1/runtimes/{runtime_id}/rollback:
19294
+ post:
19295
+ tags: [Runtimes]
19296
+ summary: Roll back to the previous image and restart
19297
+ operationId: rollbackRuntime
19298
+ description: |
19299
+ Starts the runtime again on `previous_image_digest` (recorded at each start whose
19300
+ resolved image differed). The image must still pass the allowlist. 409 when no
19301
+ previous image is recorded.
19302
+ parameters:
19303
+ - name: runtime_id
19304
+ in: path
19305
+ required: true
19306
+ schema:
19307
+ type: string
19308
+ format: uuid
19309
+ responses:
19310
+ "200":
19311
+ description: Restarting on the previous image
19312
+ content:
19313
+ application/json:
19314
+ schema:
19315
+ $ref: "#/components/schemas/RuntimeResponse"
19316
+ "401":
19317
+ $ref: "#/components/responses/Unauthorized"
19318
+ "404":
19319
+ $ref: "#/components/responses/NotFound"
19320
+ "409":
19321
+ $ref: "#/components/responses/Conflict"
19322
+
18988
19323
  /v1/runtimes/{runtime_id}/rebuild:
18989
19324
  parameters:
18990
19325
  - name: runtime_id
@@ -28095,6 +28430,138 @@ components:
28095
28430
  format: uuid
28096
28431
  description: Control-plane approval when rolling back to a wider spec.
28097
28432
 
28433
+ LlmModelPrice:
28434
+ type: object
28435
+ required: [id, provider, model_pattern, input_micro_usd_per_mtok, output_micro_usd_per_mtok, source, updated_at]
28436
+ properties:
28437
+ id: { type: string, format: uuid }
28438
+ org_id:
28439
+ type: string
28440
+ format: uuid
28441
+ nullable: true
28442
+ description: Null for a global row.
28443
+ provider: { type: string }
28444
+ model_pattern: { type: string }
28445
+ input_micro_usd_per_mtok: { type: integer, format: int64 }
28446
+ output_micro_usd_per_mtok: { type: integer, format: int64 }
28447
+ source: { type: string }
28448
+ updated_at: { type: string, format: date-time }
28449
+ AiSpendTotals:
28450
+ type: object
28451
+ properties:
28452
+ cost_usd: { type: number }
28453
+ tokens_input: { type: integer, format: int64 }
28454
+ tokens_output: { type: integer, format: int64 }
28455
+ tokens: { type: integer, format: int64 }
28456
+ requests: { type: integer, format: int64 }
28457
+ blocked: { type: integer, format: int64 }
28458
+ unpriced_requests: { type: integer, format: int64 }
28459
+ agents: { type: integer, format: int64 }
28460
+ models: { type: integer, format: int64 }
28461
+ avg_cost_per_day: { type: number }
28462
+ cost_per_request: { type: number }
28463
+ cost_per_mtok: { type: number }
28464
+ AiSpend:
28465
+ type: object
28466
+ required: [window, totals, previous, series, by_provider, by_model, by_agent, limits, generated_at]
28467
+ properties:
28468
+ generated_at: { type: string, format: date-time }
28469
+ window:
28470
+ type: object
28471
+ properties:
28472
+ from: { type: string, format: date-time }
28473
+ to: { type: string, format: date-time }
28474
+ interval: { type: string }
28475
+ previous_from: { type: string, format: date-time }
28476
+ previous_to: { type: string, format: date-time }
28477
+ days: { type: number }
28478
+ totals:
28479
+ $ref: "#/components/schemas/AiSpendTotals"
28480
+ previous:
28481
+ $ref: "#/components/schemas/AiSpendTotals"
28482
+ series:
28483
+ type: array
28484
+ items:
28485
+ type: object
28486
+ properties:
28487
+ bucket: { type: string, format: date-time }
28488
+ provider: { type: string }
28489
+ cost_usd: { type: number }
28490
+ tokens: { type: integer, format: int64 }
28491
+ requests: { type: integer, format: int64 }
28492
+ by_provider:
28493
+ type: array
28494
+ items:
28495
+ type: object
28496
+ properties:
28497
+ provider: { type: string }
28498
+ cost_usd: { type: number }
28499
+ tokens: { type: integer, format: int64 }
28500
+ requests: { type: integer, format: int64 }
28501
+ previous_cost_usd: { type: number }
28502
+ share_pct: { type: number }
28503
+ trend_pct: { type: number, nullable: true }
28504
+ by_model:
28505
+ type: array
28506
+ items:
28507
+ type: object
28508
+ properties:
28509
+ provider: { type: string }
28510
+ model: { type: string }
28511
+ cost_usd: { type: number }
28512
+ tokens_input: { type: integer, format: int64 }
28513
+ tokens_output: { type: integer, format: int64 }
28514
+ requests: { type: integer, format: int64 }
28515
+ previous_cost_usd: { type: number }
28516
+ priced: { type: boolean }
28517
+ share_pct: { type: number }
28518
+ trend_pct: { type: number, nullable: true }
28519
+ by_agent:
28520
+ type: array
28521
+ items:
28522
+ type: object
28523
+ properties:
28524
+ agent_id: { type: string, format: uuid }
28525
+ agent_name: { type: string }
28526
+ is_active: { type: boolean }
28527
+ cost_usd: { type: number }
28528
+ tokens: { type: integer, format: int64 }
28529
+ requests: { type: integer, format: int64 }
28530
+ blocked: { type: integer, format: int64 }
28531
+ top_model: { type: string, nullable: true }
28532
+ top_provider: { type: string, nullable: true }
28533
+ previous_cost_usd: { type: number }
28534
+ last_request_at: { type: string, format: date-time, nullable: true }
28535
+ daily_budget_usd: { type: number, nullable: true }
28536
+ today_cost_usd: { type: number }
28537
+ blocked_by_budget: { type: integer, format: int64 }
28538
+ max_tokens_per_request: { type: integer, format: int64, nullable: true }
28539
+ max_requests_per_day: { type: integer, format: int64, nullable: true }
28540
+ share_pct: { type: number }
28541
+ trend_pct: { type: number, nullable: true }
28542
+ budget_used_pct: { type: number, nullable: true }
28543
+ limits:
28544
+ type: object
28545
+ properties:
28546
+ agents_with_daily_budget: { type: integer, format: int64 }
28547
+ agents_over_80pct: { type: integer, format: int64 }
28548
+ agents_at_cap: { type: integer, format: int64 }
28549
+ blocked_by_budget: { type: integer, format: int64 }
28550
+ router_keys:
28551
+ type: array
28552
+ items:
28553
+ type: object
28554
+ properties:
28555
+ key_id: { type: string, format: uuid }
28556
+ agent_id: { type: string, format: uuid }
28557
+ agent_name: { type: string }
28558
+ name: { type: string }
28559
+ spent_usd: { type: number }
28560
+ cap_usd: { type: number, nullable: true }
28561
+ last_used_at: { type: string, format: date-time, nullable: true }
28562
+ credit_balance_usd: { type: number }
28563
+ inspection_fees_usd: { type: number }
28564
+ billing_tier: { type: string }
28098
28565
  OrgOverview:
28099
28566
  type: object
28100
28567
  required: [generated_at, window_hours, inventory, activity, spend, health, trend]
@@ -28622,6 +29089,9 @@ components:
28622
29089
  type: object
28623
29090
  required: [id, name, agent_id, status, created_at, updated_at]
28624
29091
  properties:
29092
+ previous_image_digest:
29093
+ type: string
29094
+ nullable: true
28625
29095
  image_digest:
28626
29096
  type: string
28627
29097
  nullable: true
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1claw/openapi-spec",
3
- "version": "0.61.38",
3
+ "version": "0.61.40",
4
4
  "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
5
5
  "license": "MIT",
6
6
  "repository": {