Skip to content

Commit 01c3176

Browse files
TheodoreSpeaksTheodoreSpeaks
authored
improvement(api): unify v2 resource query layers (#6319)
* improvement(api): unify v2 resource query layers * fix(api): address v2 review findings * fix(api): preserve cancelled queue status * fix(api): guard cancelled job transitions
1 parent f32dc83 commit 01c3176

81 files changed

Lines changed: 2437 additions & 1501 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/docs/openapi-core.json‎

Lines changed: 85 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@
3232
{
3333
"name": "Usage",
3434
"description": "Check rate limits and billing usage"
35+
},
36+
{
37+
"name": "Billing",
38+
"description": "Inspect billing status and credit-denominated ledger events"
3539
}
3640
],
3741
"security": [
@@ -1014,12 +1018,12 @@
10141018
"parameters": []
10151019
}
10161020
},
1017-
"/api/v2/billing/usage": {
1021+
"/api/v2/billing/status": {
10181022
"get": {
1019-
"operationId": "getUsageSummary",
1020-
"summary": "Get Usage Summary",
1021-
"description": "Current-billing-period usage with the per-source credit breakdown (`workflow`, `sim-chat`, `knowledge-base`, …) — monitor one source's consumption directly instead of estimating it by subtraction. Sim Chat combines the internal Copilot and workspace-chat ledgers. All values are credits (1,000 credits = $5); dollar costs are not part of this surface.",
1022-
"tags": ["Usage"],
1023+
"operationId": "getBillingStatus",
1024+
"summary": "Get Billing Status",
1025+
"description": "Return the current plan, billing standing, period, and credit allowance. This endpoint never embeds ledger rows or per-source analytics; use `GET /api/v2/billing/logs` for billing history.",
1026+
"tags": ["Billing"],
10231027
"security": [
10241028
{
10251029
"apiKey": []
@@ -1033,12 +1037,12 @@
10331037
"schema": {
10341038
"type": "string"
10351039
},
1036-
"description": "Restrict to one workspace. A workspace-scoped API key is always pinned to its own workspace; passing a different id returns 403."
1040+
"description": "Resolve the status against this workspace's actual payer. A workspace-scoped API key is pinned to its own workspace; passing a different id returns 403."
10371041
}
10381042
],
10391043
"responses": {
10401044
"200": {
1041-
"description": "The current billing period's usage summary.",
1045+
"description": "The current billing status.",
10421046
"content": {
10431047
"application/json": {
10441048
"schema": {
@@ -1047,14 +1051,12 @@
10471051
"properties": {
10481052
"data": {
10491053
"type": "object",
1050-
"required": [
1051-
"period",
1052-
"totalCredits",
1053-
"bySourceCredits",
1054-
"limitCredits",
1055-
"plan"
1056-
],
1054+
"required": ["workspaceId", "period", "plan", "status", "credits"],
10571055
"properties": {
1056+
"workspaceId": {
1057+
"type": ["string", "null"],
1058+
"description": "The workspace whose payer was resolved, or null for account billing."
1059+
},
10581060
"period": {
10591061
"type": "object",
10601062
"required": ["start", "end"],
@@ -1069,40 +1071,46 @@
10691071
}
10701072
}
10711073
},
1072-
"totalCredits": {
1073-
"type": "number"
1074-
},
1075-
"bySourceCredits": {
1076-
"type": "object",
1077-
"additionalProperties": {
1078-
"type": "number"
1079-
},
1080-
"description": "Credits consumed per usage source over the billing period."
1081-
},
1082-
"limitCredits": {
1083-
"type": "number"
1084-
},
10851074
"plan": {
10861075
"type": "string"
1076+
},
1077+
"status": {
1078+
"type": "string",
1079+
"enum": ["active", "limit_exceeded", "billing_blocked"]
1080+
},
1081+
"credits": {
1082+
"type": "object",
1083+
"required": ["used", "limit", "remaining"],
1084+
"properties": {
1085+
"used": {
1086+
"type": "number"
1087+
},
1088+
"limit": {
1089+
"type": "number"
1090+
},
1091+
"remaining": {
1092+
"type": "number"
1093+
}
1094+
}
10871095
}
10881096
}
10891097
}
10901098
}
10911099
},
10921100
"example": {
10931101
"data": {
1102+
"workspaceId": null,
10941103
"period": {
10951104
"start": "2026-07-01T00:00:00.000Z",
10961105
"end": "2026-08-01T00:00:00.000Z"
10971106
},
1098-
"totalCredits": 512,
1099-
"bySourceCredits": {
1100-
"workflow": 380,
1101-
"sim-chat": 120,
1102-
"knowledge-base": 12
1103-
},
1104-
"limitCredits": 20000,
1105-
"plan": "pro"
1107+
"plan": "pro",
1108+
"status": "active",
1109+
"credits": {
1110+
"used": 512,
1111+
"limit": 20000,
1112+
"remaining": 19488
1113+
}
11061114
}
11071115
}
11081116
}
@@ -1123,12 +1131,12 @@
11231131
}
11241132
}
11251133
},
1126-
"/api/v2/billing/usage/logs": {
1134+
"/api/v2/billing/logs": {
11271135
"get": {
1128-
"operationId": "listUsageLogs",
1129-
"summary": "List Usage Logs",
1130-
"description": "Cursor-paged, credit-denominated ledger of the account's usage events. The per-source aggregate lives on `GET /api/v2/billing/usage`; this is the row-level detail. Page by passing `nextCursor` back as `cursor` and stop when it is null.",
1131-
"tags": ["Usage"],
1136+
"operationId": "listBillingLogs",
1137+
"summary": "List Billing Logs",
1138+
"description": "Cursor-paged, credit-denominated billing ledger. This endpoint returns history only and never embeds the current billing status. Page by passing `nextCursor` back as `cursor` and stop when it is null.",
1139+
"tags": ["Billing"],
11321140
"security": [
11331141
{
11341142
"apiKey": []
@@ -1226,7 +1234,15 @@
12261234
"type": "array",
12271235
"items": {
12281236
"type": "object",
1229-
"required": ["id", "createdAt", "source", "workflowName", "creditCost"],
1237+
"required": [
1238+
"id",
1239+
"createdAt",
1240+
"source",
1241+
"workspaceId",
1242+
"workflow",
1243+
"executionId",
1244+
"creditCost"
1245+
],
12301246
"properties": {
12311247
"id": {
12321248
"type": "string"
@@ -1249,9 +1265,30 @@
12491265
"voice-output"
12501266
]
12511267
},
1252-
"workflowName": {
1253-
"type": ["string", "null"],
1254-
"description": "Populated only when `source` is `workflow`."
1268+
"workspaceId": {
1269+
"type": ["string", "null"]
1270+
},
1271+
"workflow": {
1272+
"oneOf": [
1273+
{
1274+
"type": "object",
1275+
"required": ["id", "name"],
1276+
"properties": {
1277+
"id": {
1278+
"type": "string"
1279+
},
1280+
"name": {
1281+
"type": ["string", "null"]
1282+
}
1283+
}
1284+
},
1285+
{
1286+
"type": "null"
1287+
}
1288+
]
1289+
},
1290+
"executionId": {
1291+
"type": ["string", "null"]
12551292
},
12561293
"creditCost": {
12571294
"type": "number",
@@ -1272,7 +1309,9 @@
12721309
"id": "log_1",
12731310
"createdAt": "2026-07-29T18:04:11.000Z",
12741311
"source": "sim-chat",
1275-
"workflowName": null,
1312+
"workspaceId": "ws_1",
1313+
"workflow": null,
1314+
"executionId": null,
12761315
"creditCost": 12
12771316
}
12781317
],
@@ -1445,7 +1484,7 @@
14451484
},
14461485
"status": {
14471486
"type": "string",
1448-
"enum": ["queued", "processing", "completed", "failed"],
1487+
"enum": ["queued", "processing", "completed", "failed", "cancelled"],
14491488
"description": "Current status of the job.",
14501489
"example": "completed"
14511490
},

‎apps/docs/openapi-v2-files-audit.json‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -777,17 +777,28 @@
777777
"get": {
778778
"operationId": "listAuditLogs",
779779
"summary": "List Audit Logs",
780-
"description": "List audit log entries for the authenticated user's organization with opaque cursor pagination. These are organization-scoped (not workspace-scoped) enterprise endpoints: the caller must belong to an organization with an active Enterprise subscription and hold an admin or owner role — otherwise the request returns `403`. The `ipAddress` and `userAgent` fields are intentionally excluded from entries for privacy.",
780+
"description": "List audit log entries for an explicitly selected organization with opaque cursor pagination. These organization-scoped enterprise endpoints require a personal API key; workspace-scoped keys return `403`. The caller must belong to the selected organization, hold an admin or owner role, and have an active Enterprise subscription. The `ipAddress` and `userAgent` fields are intentionally excluded from entries for privacy.",
781781
"tags": ["Audit Logs"],
782782
"x-codeSamples": [
783783
{
784784
"id": "curl",
785785
"label": "cURL",
786786
"lang": "bash",
787-
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v2/audit-logs?limit=50\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
787+
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v2/audit-logs?organizationId=org_abc123&limit=50\" \\\n -H \"X-API-Key: YOUR_PERSONAL_API_KEY\""
788788
}
789789
],
790790
"parameters": [
791+
{
792+
"name": "organizationId",
793+
"in": "query",
794+
"required": true,
795+
"description": "Organization to audit. The caller must be an admin or owner of this organization.",
796+
"schema": {
797+
"type": "string",
798+
"minLength": 1,
799+
"example": "org_abc123"
800+
}
801+
},
791802
{
792803
"name": "action",
793804
"in": "query",
@@ -958,14 +969,14 @@
958969
"get": {
959970
"operationId": "getAuditLog",
960971
"summary": "Get Audit Log",
961-
"description": "Retrieve a single audit log entry by ID, scoped to the authenticated user's organization. Organization-scoped (not workspace-scoped): the caller must belong to an organization with an active Enterprise subscription and hold an admin or owner role — otherwise the request returns `403`. An entry outside your organization returns `404` (existence is not leaked). The `ipAddress` and `userAgent` fields are intentionally excluded for privacy.",
972+
"description": "Retrieve a single audit log entry by ID within an explicitly selected organization. This endpoint requires a personal API key; workspace-scoped keys return `403`. The caller must belong to the selected organization, hold an admin or owner role, and have an active Enterprise subscription. An entry outside that organization returns `404` (existence is not leaked). The `ipAddress` and `userAgent` fields are intentionally excluded for privacy.",
962973
"tags": ["Audit Logs"],
963974
"x-codeSamples": [
964975
{
965976
"id": "curl",
966977
"label": "cURL",
967978
"lang": "bash",
968-
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v2/audit-logs/{id}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
979+
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v2/audit-logs/{id}?organizationId=org_abc123\" \\\n -H \"X-API-Key: YOUR_PERSONAL_API_KEY\""
969980
}
970981
],
971982
"parameters": [
@@ -979,6 +990,17 @@
979990
"minLength": 1,
980991
"example": "audit_2c3d4e5f6g"
981992
}
993+
},
994+
{
995+
"name": "organizationId",
996+
"in": "query",
997+
"required": true,
998+
"description": "Organization that owns the audit entry. The caller must be an admin or owner of this organization.",
999+
"schema": {
1000+
"type": "string",
1001+
"minLength": 1,
1002+
"example": "org_abc123"
1003+
}
9821004
}
9831005
],
9841006
"responses": {

0 commit comments

Comments
 (0)