API Endpoints Reference

Last Updated: January 1, 2026

This document provides a comprehensive overview of all API endpoints in the Eddy application, organized by domain. All endpoints require authentication unless otherwise noted.

Overview

Eddy's API is organized into logical domains that mirror the application's architecture. The API uses a consistent pattern across all endpoints with standardized authentication, error handling, and response formats.

Quick Navigation

---

Common Patterns

Authentication

All endpoints require authentication via Auth0 session, validated using validateUser(req, res).

HTTP Methods

Note: Most endpoints use POST even for read operations, with parameters in request body rather than query strings. This is a design choice of the API.

Error Handling

Errors are handled consistently via:

• sendError(res, message, statusCode) - for validation errors
• getCatchErrors(res, error) - for caught exceptions

Soft Deletes

Most entities use soft deletes via archived_at timestamp rather than hard deletion.

Serialization

Many endpoints use serializer functions to transform database records to API responses:

• serializeBlock, serializeWorkflow, serializeWorkflowRun, etc.

Event Tracking

Critical actions emit events to:

• Database events table for audit log
• PostHog for analytics (via captureServerEvent)

Transactions

Complex multi-step operations use Knex transactions to ensure data consistency.

Response Formats

Successful responses typically return:

• Single entity: { ...entityFields }
• Multiple entities: [{...entity1}, {...entity2}]
• With related data: { ...entity, relatedEntities: [...] }

---

Authentication

POST /api/auth/[auth0]

Handles Auth0 authentication flows including login and callback.

• Login: Initiates authentication with Auth0, supports redirectUrl and loginHint query params
• Callback: Processes Auth0 callback, creates new users or retrieves existing users by email, stores user in session
• Creates: User records in database on first login
• Events: Emits user_created event for new users

---

Workflows

Workflows are the core templates for processes that can be instantiated as workflow runs (sessions).

POST /api/workflows/index

Get a specific workflow by ID with complete structure.

• Params: id (workflow_id)
• Returns: Workflow with pages, sections, blocks, and page trees
• Service: Uses getWorkflowById

POST /api/workflows/create

Create a new workflow.

• Params: name, group_id, scaffold_sheet, description, singleton, scaffold_sheet_id
• Returns: Created workflow record
• Events: workflow_created PostHog event
• Service: Uses createWorkflow

POST /api/workflows/update

Update an existing workflow.

• Params: id, plus any updatable fields (name, description, singleton, published_at, etc.)
• Returns: Updated workflow record
• Service: Uses updateWorkflow

POST /api/workflows/delete

Soft delete a workflow (sets archived_at).

• Params: id (workflow_id)
• Returns: Success message
• Service: Uses deleteWorkflow

POST /api/workflows/duplicate

Duplicate a workflow with all its pages, blocks, and structure.

• Params: id (source workflow_id), name (new workflow name)
• Returns: New workflow record
• Service: Uses duplicateWorkflow

POST /api/workflows/list

List all workflows for a group.

• Params: group_id
• Returns: Array of workflows
• Service: Uses getWorkflowsByGroupId

---

Workflow Runs (Sessions)

Workflow runs are live instances of workflow execution.

POST /api/workflow_runs/index

Get a specific workflow run with complete state.

• Params: id (workflow_run_id)
• Returns: Workflow run with stages, assignments, and current state
• Service: Uses getWorkflowRunById

POST /api/workflow_runs/create

Create a new workflow run (start a session).

• Params: workflow_id, group_id, optional role assignments
• Returns: Created workflow run record
• Events: workflow_run_created event
• Service: Uses createWorkflowRun

POST /api/workflow_runs/update

Update a workflow run.

• Params: id, plus updatable fields
• Returns: Updated workflow run record
• Service: Uses updateWorkflowRun

POST /api/workflow_runs/delete

Soft delete a workflow run.

• Params: id (workflow_run_id)
• Returns: Success message
• Service: Uses deleteWorkflowRun

POST /api/workflow_runs/list

List workflow runs for a group or workflow.

• Params: group_id or workflow_id, optional filters
• Returns: Array of workflow runs
• Service: Uses query builder with filters

---

Workflow Run Stages

Stages represent the current state of pages within a workflow run.

POST /api/workflow_run_stages/update

Update a stage (e.g., mark as complete, update data).

• Params: id (stage_id), updatable fields
• Returns: Updated stage record
• Service: Uses updateWorkflowRunStage

POST /api/workflow_run_stages/complete

Mark a stage as complete and progress the workflow.

• Params: id (stage_id)
• Returns: Updated stage and next available stages
• Events: stage_completed event
• Service: Uses stage progression logic

---

Pages

Pages are the individual steps/screens in a workflow.

POST /api/pages/index

Get a specific page with its sections and blocks.

• Params: id (page_id)
• Returns: Page with nested sections and blocks
• Service: Uses getPageById

POST /api/pages/create

Create a new page in a workflow.

• Params: workflow_id, name, description
• Returns: Created page record
• Service: Uses createPage

POST /api/pages/update

Update a page.

• Params: id, updatable fields
• Returns: Updated page record
• Service: Uses updatePage

POST /api/pages/delete

Soft delete a page.

• Params: id (page_id)
• Returns: Success message
• Service: Uses deletePage

---

Page Transitions

Transitions define the flow between pages in a workflow.

POST /api/page_transitions/create

Create a transition between two pages.

• Params: from_page_id, to_page_id, workflow_id, optional conditions
• Returns: Created transition record
• Service: Uses createPageTransition

POST /api/page_transitions/update

Update a transition (e.g., modify conditions).

• Params: id, updatable fields including conditions
• Returns: Updated transition record
• Service: Uses updatePageTransition

POST /api/page_transitions/delete

Delete a transition.

• Params: id (transition_id)
• Returns: Success message
• Service: Uses deletePageTransition

---

Sections

Sections are containers for blocks within a page.

POST /api/sections/create

Create a new section in a page.

• Params: page_id, type, name
• Returns: Created section record
• Service: Uses createSection

POST /api/sections/update

Update a section.

• Params: id, updatable fields
• Returns: Updated section record
• Service: Uses updateSection

POST /api/sections/delete

Delete a section.

• Params: id (section_id)
• Returns: Success message
• Service: Uses deleteSection

---

Blocks

Blocks are the atomic units of content and user input in workflows.

POST /api/blocks/create

Create a new block in a section.

• Params: section_id, type, label, options, optional sheet_id, column_id
• Returns: Created block record
• Service: Uses createBlock

POST /api/blocks/update

Update a block.

• Params: id, updatable fields
• Returns: Updated block record
• Service: Uses updateBlock

POST /api/blocks/delete

Delete a block.

• Params: id (block_id)
• Returns: Success message
• Service: Uses deleteBlock

POST /api/blocks/reorder

Reorder blocks within a section.

• Params: section_id, block_ids (array in desired order)
• Returns: Success message
• Service: Updates sort_order for each block

---

Groups

Groups (workspaces) are the top-level organizational unit.

POST /api/groups/index

Get a specific group.

• Params: id (group_id)
• Returns: Group record
• Service: Uses getGroupById

POST /api/groups/create

Create a new group.

• Params: name, description
• Returns: Created group record
• Events: group_created event
• Service: Uses createGroup

POST /api/groups/update

Update a group.

• Params: id, updatable fields
• Returns: Updated group record
• Service: Uses updateGroup

POST /api/groups/list

List all groups for the current user.

• Returns: Array of groups the user is a member of
• Service: Joins groups with memberships

---

Memberships

Memberships define user access to groups.

POST /api/memberships/create

Add a user to a group.

• Params: group_id, user_id, role
• Returns: Created membership record
• Service: Uses createMembership

POST /api/memberships/update

Update a membership (e.g., change role).

• Params: id, updatable fields
• Returns: Updated membership record
• Service: Uses updateMembership

POST /api/memberships/delete

Remove a user from a group.

• Params: id (membership_id)
• Returns: Success message
• Service: Uses deleteMembership

---

Sheets

Sheets are structured data tables that store workflow outputs.

POST /api/sheets/index

Get a specific sheet with its columns.

• Params: id (sheet_id)
• Returns: Sheet with columns array
• Service: Uses getSheetById

POST /api/sheets/create

Create a new sheet.

• Params: group_id, name, description
• Returns: Created sheet record
• Events: sheet_created event
• Service: Uses createSheet

POST /api/sheets/update

Update a sheet.

• Params: id, updatable fields
• Returns: Updated sheet record
• Service: Uses updateSheet

POST /api/sheets/delete

Soft delete a sheet.

• Params: id (sheet_id)
• Returns: Success message
• Service: Uses deleteSheet

POST /api/sheets/data/sheet

Get sheet data with rows, columns, and optional filtering.

• Params: sheet_id, optional filters, sort, pagination
• Returns: Comprehensive sheet data object with rows and columns
• Service: Complex query builder with AG Grid support

---

Columns

Columns define the structure of data in sheets.

POST /api/columns/create

Create a new column in a sheet.

• Params: sheet_id, name, type, optional options
• Returns: Created column record
• Service: Uses createColumn

POST /api/columns/update

Update a column.

• Params: id, updatable fields
• Returns: Updated column record
• Service: Uses updateColumn

POST /api/columns/delete

Delete a column.

• Params: id (column_id)
• Returns: Success message
• Service: Uses deleteColumn

---

Rows

Rows are individual records in sheets.

POST /api/rows/create

Create a new row in a sheet.

• Params: sheet_id, optional data
• Returns: Created row record
• Service: Uses createRow

POST /api/rows/update

Update a row.

• Params: id, updatable fields
• Returns: Updated row record
• Service: Uses updateRow

POST /api/rows/delete

Soft delete a row.

• Params: id (row_id)
• Returns: Success message
• Service: Uses deleteRow

---

Cells

Cells store individual data values in sheet rows.

POST /api/cells/update

Update a cell value.

• Params: row_id, column_id, value
• Returns: Updated cell record
• Service: Uses updateCell with validation
• Events: cell_updated event

POST /api/cells/bulk_update

Update multiple cells at once.

• Params: Array of { row_id, column_id, value }
• Returns: Array of updated cells
• Service: Uses transaction for atomicity

---

Users

POST /api/users/index

Get a specific user.

• Params: id (user_id)
• Returns: User record (sanitized)
• Service: Uses getUserById

POST /api/users/list

List users (typically for a group).

• Params: Optional group_id filter
• Returns: Array of users
• Service: Query builder with optional group filter

---

Me (Current User)

GET /api/me

Get current authenticated user with their groups and permissions.

• Returns: Current user with memberships and groups
• Service: Uses session user ID

POST /api/me/update

Update current user profile.

• Params: Updatable user fields
• Returns: Updated user record
• Service: Uses updateUser

---

Notifications

POST /api/notifications/list

List notifications for current user.

• Params: Optional read filter, pagination
• Returns: Array of notifications
• Service: Query builder with user filter

POST /api/notifications/mark_read

Mark notification(s) as read.

• Params: id or ids (array)
• Returns: Success message
• Service: Updates read_at timestamp

---

Additional Domains

The API includes many more domains for specialized functionality:

• Discussions & Comments - Threaded conversations
• Polls & Votes - Decision-making features
• Follows & Mentions - Social features
• Shortcuts - Quick access links
• Attachments - File uploads and management
• Events - Audit logging
• Analytics - Process intelligence
• Inngest - Background job processing

For detailed information on these domains, refer to the source code in /pages/api/.

---

Development & Testing

POST /api/dev/seed

Seed the database with test data (development only).

• Environment: Only available in development
• Returns: Success message with created entities
• Service: Creates sample workflows, users, and data

POST /api/dev/reset

Reset the database (development only).

• Environment: Only available in development
• Returns: Success message
• Service: Truncates all tables

---

Best Practices

When Building New Endpoints

1. Follow the pattern: Use existing endpoints as templates
2. Validate input: Always validate request parameters
3. Use services: Extract business logic into service functions
4. Handle errors: Use consistent error handling patterns
5. Emit events: Track important actions for audit and analytics
6. Use transactions: For multi-step operations that must be atomic
7. Serialize responses: Transform database records before returning
8. Document: Add JSDoc comments and update this reference

When Calling Endpoints

1. Authenticate: Ensure user is logged in
2. Handle errors: Check for error responses and display appropriately
3. Use hooks: Leverage React Query hooks for data fetching
4. Cache wisely: Use appropriate cache keys and invalidation
5. Optimistic updates: For better UX on mutations

---

Related Documentation