API Reference

Relevant source files

• apps/sim/app/api/folders/[id]/route.ts
• apps/sim/app/api/folders/route.ts
• apps/sim/app/api/knowledge/[id]/documents/[documentId]/route.ts
• apps/sim/app/api/schedules/[id]/route.ts
• apps/sim/app/api/schedules/route.test.ts
• apps/sim/app/api/schedules/route.ts
• apps/sim/app/api/workflows/[id]/duplicate/route.ts
• apps/sim/app/api/workflows/[id]/route.test.ts
• apps/sim/app/api/workflows/[id]/route.ts
• apps/sim/app/api/workflows/[id]/state/route.ts
• apps/sim/app/api/workflows/[id]/variables/route.test.ts
• apps/sim/app/api/workflows/[id]/variables/route.ts
• apps/sim/app/api/workflows/route.ts
• apps/sim/app/api/workspaces/route.ts
• apps/sim/app/chat/constants.ts
• apps/sim/app/workspace/[workspaceId]/w/components/sidebar/hooks/index.ts
• apps/sim/app/workspace/[workspaceId]/w/components/sidebar/hooks/use-workflow-operations.ts
• apps/sim/app/workspace/[workspaceId]/w/components/sidebar/hooks/use-workspace-management.ts
• apps/sim/app/workspace/[workspaceId]/w/hooks/use-delete-folder.ts
• apps/sim/app/workspace/[workspaceId]/w/hooks/use-duplicate-folder.ts
• apps/sim/app/workspace/[workspaceId]/w/hooks/use-duplicate-workflow.ts
• apps/sim/blocks/blocks/api_trigger.ts
• apps/sim/blocks/blocks/chat_trigger.ts
• apps/sim/blocks/blocks/input_trigger.ts
• apps/sim/blocks/blocks/manual_trigger.ts
• apps/sim/hooks/queries/folders.ts
• apps/sim/hooks/queries/workflows.ts
• apps/sim/hooks/queries/workspace.ts
• apps/sim/stores/folders/store.ts

This document provides a comprehensive overview of the Sim Studio REST API architecture, authentication patterns, request/response conventions, and endpoint structure. The API follows RESTful principles and is built on Next.js 16 API routes.

For detailed endpoint documentation by category, see:

• Workflow APIs — Workflow CRUD, state management, and variables.
• Execution APIs — Workflow execution and control.
• Deployment APIs — Deployment and versioning.
• Copilot APIs — AI assistant chat and context.
• Webhook & Trigger APIs — Webhook handling and triggers.
• Logs & Analytics APIs — Execution logs and analytics.
• Workspace & Organization APIs — Workspace management and invitations.
• Authentication APIs — Session and OAuth lifecycle.
• A2A Protocol & Agent-to-Agent APIs — Cross-agent tasking and discovery.

---

API Architecture Overview

The Sim API is organized into functional domains, each implemented as Next.js API routes. All endpoints are RESTful HTTP endpoints that accept and return JSON. The system uses a centralized withRouteHandler wrapper to provide consistent error handling, request ID generation, and logging across all endpoints apps/sim/app/api/workflows/route.ts23

API Surface Organization

Sources: apps/sim/app/api/workflows/route.ts23-140 apps/sim/app/api/workflows/[id]/route.ts:30-169, apps/sim/app/api/schedules/route.ts27-199 apps/sim/app/api/folders/route.ts1-50

---

Authentication & Authorization

Hybrid Authentication

The API uses a hybrid approach to authentication. Most endpoints support both browser-based sessions (via Better Auth) and programmatic access (via API Keys or Internal JWTs). Identity verification is handled by checkSessionOrInternalAuth or checkHybridAuth apps/sim/app/api/workflows/[id]/route.ts:37-41.

Authentication Flow:

Authorization Patterns: Sim Studio employs a granular permission system. After authentication, endpoints call authorizeWorkflowByWorkspacePermission to ensure the user has the required read, write, or admin access for the specific resource apps/sim/app/api/workflows/[id]/route.ts:68-72.

Sources: apps/sim/app/api/workflows/[id]/route.ts:37-87, apps/sim/app/api/workflows/[id]/state/route.ts:41-53, apps/sim/app/api/workspaces/route.ts31-36

---

Workflow Execution & Scheduling

Workflows can be executed synchronously via REST or scheduled as recurring jobs. The scheduling system allows for both workflow-linked triggers and standalone "job" schedules apps/sim/app/api/schedules/route.ts21-26

Scheduling Flow Mapping:

Key Scheduling Endpoints:

• GET /api/schedules: Retrieve schedules for a workflow or all schedules for a workspace apps/sim/app/api/schedules/route.ts27-124
• POST /api/schedules: Create a standalone scheduled job with a specific prompt and cron expression apps/sim/app/api/schedules/route.ts199-207
• PUT /api/schedules/[id]: Enable, disable, or update an existing schedule apps/sim/app/api/schedules/[id]/route.ts:101-161.

Sources: apps/sim/app/api/schedules/route.ts27-207 apps/sim/app/api/schedules/[id]/route.ts:101-180, apps/sim/lib/workflows/schedules/utils.ts15-18

---

Workflow Management & State

Workflows are managed through a set of CRUD endpoints. A key feature is the "Normalized State" system where workflow blocks and edges are stored in specific relational tables rather than a single JSON blob apps/sim/app/api/workflows/[id]/state/route.ts:103-105.

Workflow Data Mapping:

Key Endpoints:

• GET /api/workflows/[id]: Fetch a single workflow, attempting to load from normalized tables first apps/sim/app/api/workflows/[id]/route.ts:30-112.
• PUT /api/workflows/[id]/state: Persist full canvas state, including sanitization of agent tools in blocks apps/sim/app/api/workflows/[id]/state/route.ts:106-160.
• POST /api/workflows/[id]/duplicate: Duplicate a workflow and its associated blocks/edges apps/sim/app/api/workflows/[id]/duplicate/route.ts:17-49.

Sources: apps/sim/app/api/workflows/[id]/route.ts:30-162, apps/sim/app/api/workflows/[id]/state/route.ts:36-175, apps/sim/app/api/workflows/[id]/duplicate/route.ts:17-95

---

Error Handling & Validation

Request validation is strictly enforced using Zod contracts via parseRequest apps/sim/app/api/workflows/[id]/state/route.ts:120-122.

Status Code	Scenario	Reference
400	Schema validation fails or invalid query parameters	apps/sim/app/api/workflows/route.ts28-33
401	Invalid session or missing API credentials	apps/sim/app/api/workflows/[id]/route.ts:38-41
403	User lacks permission for workspace or workflow	apps/sim/app/api/workflows/[id]/route.ts:79-85
404	Resource not found (Workflow, Schedule, Folder)	apps/sim/app/api/workflows/[id]/route.ts:48-51
423	Resource is locked (Workflow or Folder)	apps/sim/app/api/workflows/[id]/duplicate/route.ts:121-123
500	Internal server error	apps/sim/app/api/workflows/[id]/route.ts:157-161

Sources: apps/sim/lib/api/server.ts9-14 apps/sim/app/api/workflows/[id]/route.ts:30-161, apps/sim/app/api/workflows/[id]/duplicate/route.ts:96-136

---

Next Steps

For detailed documentation on specific endpoint categories:

• Workflow APIs — Workflow CRUD and variable management.
• Execution APIs — Execution parameters and response formats.
• Deployment APIs — Workflow versioning and deployment.
• Copilot APIs — Chat modes and message management.
• Webhook & Trigger APIs — Webhook verification and path triggers.
• Logs & Analytics APIs — Log retrieval and cursor pagination.
• Workspace & Organization APIs — Permissions and organization management.
• Authentication APIs — Better Auth and session lifecycle.
• A2A Protocol & Agent-to-Agent APIs — Cross-agent tasking and discovery.