Skip to main content

​
Architecture

DelightBridge uses Next.js 15 API Routes with the App Router convention. All API endpoints are defined as route.ts files within the /src/app/api directory structure.

​
Base URL

The API is served from the same domain as your DelightBridge application: 
https://your-domain.com/api
For local development: 
http://localhost:3000/api

​
Request Format

​
HTTP Methods

DelightBridge API follows REST conventions:
  • GET - Retrieve resources
  • POST - Create new resources
  • PATCH - Update existing resources
  • DELETE - Remove resources

​
Content Type

All request bodies must be sent as JSON: 
Content-Type: application/json

​
Example Request

curl -X GET 'https://your-domain.com/api/threads?serviceId=service-123&limit=50' \
  -H 'Cookie: authjs.session-token=YOUR_SESSION_TOKEN' \
  -H 'Content-Type: application/json'

​
Response Format

​
Success Responses

Successful requests return JSON data with appropriate HTTP status codes:
  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
Example: Get Threads
[
  {
    "id": "thread-123",
    "serviceId": "service-456",
    "subject": "Question about pricing",
    "customerEmail": "[email protected]",
    "customerName": "Jane Smith",
    "status": "inbox",
    "isRead": false,
    "lastMessageAt": "2026-03-01T10:30:00.000Z",
    "messageCount": 3
  }
]

​
Error Responses

Errors return JSON objects with an error field and appropriate HTTP status codes: 
{
  "error": "serviceId required"
}

​
Error Status Codes

Status CodeMeaningWhen It Occurs
400Bad RequestMissing required parameters, invalid input
401UnauthorizedNo valid session (not logged in)
403ForbiddenInsufficient permissions for the operation
404Not FoundResource doesn’t exist
409ConflictDuplicate action prevented (e.g., already sent)
500Internal Server ErrorServer-side error or external API failure

​
Common Patterns

​
Query Parameters

Many GET endpoints accept query parameters for filtering and pagination: 
GET /api/threads?serviceId=service-123&limit=100&includeMessages=1
​
serviceId
string
required
The ID of the service/account to filter by
​
limit
number
default:"100"
Maximum number of results (1-200)
​
includeMessages
string
Set to 1 to include full message bodies

​
Dynamic Routes

Resource-specific operations use dynamic route segments: 
PATCH /api/services/[id]         # Update a service
DELETE /api/members/[email]      # Remove a member
POST /api/threads/[id]/send      # Send a draft

​
Timestamps

All timestamps are returned as ISO 8601 strings in UTC: 
"lastMessageAt": "2026-03-01T10:30:00.000Z"

​
Rate Limiting

Currently, DelightBridge does not implement rate limiting on API endpoints. This may change in future versions for production deployments.

​
Available Endpoints

The API is organized into the following resource groups:

Services

Manage email service accounts and their configurations

Threads

List and manage email conversation threads

Drafts

Create, update, and generate AI-powered draft responses

Members

Manage workspace members and permissions (admin only)

​
Authentication

All API endpoints require authentication. See the Authentication guide for details on how to authenticate your requests.
Security Note: Always use HTTPS in production. Never expose session tokens in client-side code or logs.

Build docs developers (and LLMs) love

Get started for freeTalk to us