Skip to content

improvement(api): unify v2 resource query layers #6319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheodoreSpeaks merged 4 commits into from
Aug 6, 2026
Merged

improvement(api): unify v2 resource query layers #6319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
28269b5
improvement(api): unify v2 resource query layers
TheodoreSpeaks Aug 6, 2026
6b8806c
fix(api): address v2 review findings
TheodoreSpeaks Aug 6, 2026
0892cdb
fix(api): preserve cancelled queue status
TheodoreSpeaks Aug 6, 2026
141d697
fix(api): guard cancelled job transitions
TheodoreSpeaks Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 85 additions & 46 deletions apps/docs/openapi-core.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@
{
"name": "Usage",
"description": "Check rate limits and billing usage"
},
{
"name": "Billing",
"description": "Inspect billing status and credit-denominated ledger events"
}
],
"security": [
Expand Down Expand Up @@ -1014,12 +1018,12 @@
"parameters": []
}
},
"/api/v2/billing/usage": {
"/api/v2/billing/status": {
"get": {
"operationId": "getUsageSummary",
"summary": "Get Usage Summary",
"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.",
"tags": ["Usage"],
"operationId": "getBillingStatus",
"summary": "Get Billing Status",
"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.",
"tags": ["Billing"],
"security": [
{
"apiKey": []
Expand All @@ -1033,12 +1037,12 @@
"schema": {
"type": "string"
},
"description": "Restrict to one workspace. A workspace-scoped API key is always pinned to its own workspace; passing a different id returns 403."
"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."
}
],
"responses": {
"200": {
"description": "The current billing period's usage summary.",
"description": "The current billing status.",
"content": {
"application/json": {
"schema": {
Expand All @@ -1047,14 +1051,12 @@
"properties": {
"data": {
"type": "object",
"required": [
"period",
"totalCredits",
"bySourceCredits",
"limitCredits",
"plan"
],
"required": ["workspaceId", "period", "plan", "status", "credits"],
"properties": {
"workspaceId": {
"type": ["string", "null"],
"description": "The workspace whose payer was resolved, or null for account billing."
},
"period": {
"type": "object",
"required": ["start", "end"],
Expand All @@ -1069,40 +1071,46 @@
}
}
},
"totalCredits": {
"type": "number"
},
"bySourceCredits": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Credits consumed per usage source over the billing period."
},
"limitCredits": {
"type": "number"
},
"plan": {
"type": "string"
},
"status": {
"type": "string",
"enum": ["active", "limit_exceeded", "billing_blocked"]
},
"credits": {
"type": "object",
"required": ["used", "limit", "remaining"],
"properties": {
"used": {
"type": "number"
},
"limit": {
"type": "number"
},
"remaining": {
"type": "number"
}
}
}
}
}
}
},
"example": {
"data": {
"workspaceId": null,
"period": {
"start": "2026-07-01T00:00:00.000Z",
"end": "2026-08-01T00:00:00.000Z"
},
"totalCredits": 512,
"bySourceCredits": {
"workflow": 380,
"sim-chat": 120,
"knowledge-base": 12
},
"limitCredits": 20000,
"plan": "pro"
"plan": "pro",
"status": "active",
"credits": {
"used": 512,
"limit": 20000,
"remaining": 19488
}
}
}
}
Expand All @@ -1123,12 +1131,12 @@
}
}
},
"/api/v2/billing/usage/logs": {
"/api/v2/billing/logs": {
"get": {
"operationId": "listUsageLogs",
"summary": "List Usage Logs",
"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.",
"tags": ["Usage"],
"operationId": "listBillingLogs",
"summary": "List Billing Logs",
"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.",
"tags": ["Billing"],
"security": [
{
"apiKey": []
Expand Down Expand Up @@ -1226,7 +1234,15 @@
"type": "array",
"items": {
"type": "object",
"required": ["id", "createdAt", "source", "workflowName", "creditCost"],
"required": [
"id",
"createdAt",
"source",
"workspaceId",
"workflow",
"executionId",
"creditCost"
],
"properties": {
"id": {
"type": "string"
Expand All @@ -1249,9 +1265,30 @@
"voice-output"
]
},
"workflowName": {
"type": ["string", "null"],
"description": "Populated only when `source` is `workflow`."
"workspaceId": {
"type": ["string", "null"]
},
"workflow": {
"oneOf": [
{
"type": "object",
"required": ["id", "name"],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": ["string", "null"]
}
}
},
{
"type": "null"
}
]
},
"executionId": {
"type": ["string", "null"]
},
"creditCost": {
"type": "number",
Expand All @@ -1272,7 +1309,9 @@
"id": "log_1",
"createdAt": "2026-07-29T18:04:11.000Z",
"source": "sim-chat",
"workflowName": null,
"workspaceId": "ws_1",
"workflow": null,
"executionId": null,
"creditCost": 12
}
],
Expand Down Expand Up @@ -1445,7 +1484,7 @@
},
"status": {
"type": "string",
"enum": ["queued", "processing", "completed", "failed"],
"enum": ["queued", "processing", "completed", "failed", "cancelled"],
"description": "Current status of the job.",
"example": "completed"
},
Expand Down
30 changes: 26 additions & 4 deletions apps/docs/openapi-v2-files-audit.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -777,17 +777,28 @@
"get": {
"operationId": "listAuditLogs",
"summary": "List Audit Logs",
"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.",
"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.",
"tags": ["Audit Logs"],
"x-codeSamples": [
{
"id": "curl",
"label": "cURL",
"lang": "bash",
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v2/audit-logs?limit=50\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
"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\""
}
],
"parameters": [
{
"name": "organizationId",
"in": "query",
"required": true,
"description": "Organization to audit. The caller must be an admin or owner of this organization.",
"schema": {
"type": "string",
"minLength": 1,
"example": "org_abc123"
}
},
{
"name": "action",
"in": "query",
Expand Down Expand Up @@ -958,14 +969,14 @@
"get": {
"operationId": "getAuditLog",
"summary": "Get Audit Log",
"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.",
"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.",
"tags": ["Audit Logs"],
"x-codeSamples": [
{
"id": "curl",
"label": "cURL",
"lang": "bash",
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v2/audit-logs/{id}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
"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\""
}
],
"parameters": [
Expand All @@ -979,6 +990,17 @@
"minLength": 1,
"example": "audit_2c3d4e5f6g"
}
},
{
"name": "organizationId",
"in": "query",
"required": true,
"description": "Organization that owns the audit entry. The caller must be an admin or owner of this organization.",
"schema": {
"type": "string",
"minLength": 1,
"example": "org_abc123"
}
}
],
"responses": {
Expand Down
Loading
Loading