improvement(api): unify v2 resource query layers

[TheodoreSpeaks]

Summary

• split billing status and ledger logs and make execution IDs the public log identity
• share execution, log, workflow, deployment, and knowledge read/query layers across API adapters
• tighten billing, audit, cursor, and cancellation authorization/correctness and refresh OpenAPI specs

Type of Change

• Improvement
• Bug fix

Testing

• 204 targeted tests passing
• full lint and repository audit suite passing
• strict API validation and OpenAPI validation passing

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 6, 2026 8:36am

[cursor]

PR Summary

High Risk
Large, versioned public API contract changes (billing paths, log identity, audit org scoping) plus shared auth/query refactors across billing, logs, and workflows; clients and integrators must migrate, though behavior is covered by extensive tests.

Overview
This PR reshapes several v2 public APIs and centralizes read/query logic so v1/v2 route handlers share the same layers instead of duplicating SQL.

Billing replaces GET /api/v2/billing/usage and GET /api/v2/billing/usage/logs with /api/v2/billing/status (plan, standing, credit allowance only) and /api/v2/billing/logs (cursor-paged ledger). Ledger rows now include workspaceId, structured workflow, and executionId. Workspace-scoped billing reads go through resolveWorkspaceAccess before loading data.

Logs and executions treat executionId as the only public identifier: list/detail schemas drop separate log IDs, add status, and detail responses use top-level workflowState, traceSpans, and finalOutput instead of nested executionData. The separate /api/v2/logs/executions/{executionId} route is removed; v1/v2 adapters use getPublicWorkflowLog / listPublicWorkflowLogs.

Workflows adds GET /api/v2/workflows/{id}/executions for durable history (filters, cursor pagination; queued is not a history filter). Workflow list/read paths use shared listWorkspaceWorkflows, loadWorkflowReadSnapshot, and resolveV2WorkflowTarget / getDeploymentWorkflowTarget.

Audit logs require a mandatory organizationId, personal API keys only, and authorization against that org before querying.

Knowledge moves search query helpers to lib/knowledge/search/queries and document lookups to getKnowledgeDocument. v2 knowledge search consolidates on executeKnowledgeSearch.

Execution cancellation verifies the execution belongs to the workflow, can cancel queued async jobs, and treats missing executions as 404. Stale-job cleanup retention now includes cancelled jobs. OpenAPI specs are updated to match.

^{Reviewed by Cursor Bugbot for commit 141d697. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR consolidates execution, log, workflow, deployment, knowledge, billing, and audit query behavior behind shared service layers while updating the corresponding API contracts.

• Makes execution IDs the public identity for execution logs and binds pagination cursors to their sort order.
• Separates billing status from billing-ledger history and tightens organization, workspace, and cancellation handling.
• Refreshes v2 adapters, tests, queue status behavior, and OpenAPI specifications.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/logs/public-queries.ts	Introduces shared public-log list/detail queries with order-bound keyset cursors and consistent execution identity.
apps/sim/lib/workflows/executor/execution-queries.ts	Centralizes workflow-execution listing, ownership checks, status projection, and sorted pagination.
apps/sim/lib/execution/cancel-workflow-execution.ts	Extends cancellation to active queue jobs and validates that an execution belongs to the requested workflow.
apps/sim/lib/execution/cancellation.ts	Extends durable cancellation markers to the configured maximum job lifetime.
apps/sim/lib/knowledge/documents/service.ts	Provides a shared document lookup that retains excluded, archived, and deleted lifecycle filtering.
apps/sim/app/api/v1/logs/executions/[executionId]/route.ts	Reuses the shared execution-log query and replaces the previous untyped workflow-state diagnostic access with explicit narrowing.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[API client] --> Adapter[v1 / v2 API adapter]
  Adapter --> Auth[Authentication and authorization]
  Auth --> Shared[Shared resource query layer]
  Shared --> DB[(Postgres)]
  Shared --> Queue[Execution queue]
  Adapter --> Contract[Versioned response contract]
  Contract --> Client

Loading

_{Reviews (4): Last reviewed commit: "fix(api): guard cancelled job transition..." | Re-trigger Greptile}

[TheodoreSpeaks]

Review follow-up in 6b8806c: queued workflow cancellation now resolves the deterministic execution job to its provider run and calls the queue backend cancellation API. The Redis cancellation backstop also now lives for the queue maximum lifetime instead of one hour, so a delayed worker cannot outlive the cancellation marker. Focused cancellation and Trigger.dev lookup tests cover both paths.

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6b8806c. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 141d697. Configure here.}