Skip to main content

​
Overview

DayCopilot is an AI-powered productivity platform that automatically processes emails to extract tasks and events, and provides a comprehensive REST API for building productivity applications.
This document focuses on the aspects of DayCopilot’s architecture that are relevant for API integrators. Internal implementation details are omitted for clarity.

​
System Architecture

​
Core Services

DayCopilot exposes the following services through the API:

​
REST API

  • Standards-compliant REST endpoints
  • OpenAPI 3.0 specification
  • JSON request/response format
  • Comprehensive error handling

​
OAuth Service

  • Industry-standard OAuth 2.0
  • Fine-grained permission scopes
  • JWT token-based authentication
  • Automatic token refresh

​
Email Processing

  • AI-powered email parsing
  • Automatic task/event extraction
  • Async processing pipeline
  • Real-time notifications

​
Calendar Sync

  • Bidirectional CalDAV integration
  • RFC 5545 compliant (iCalendar)
  • Timezone handling
  • RSVP status tracking

​
Data Model

Understanding the core data model helps you build effective integrations:

​
Tasks

Tasks represent actionable items that need to be completed. Key Properties:
  • Unique ID (UUID)
  • Title and description
  • Priority levels (low, medium, high, urgent)
  • Status (pending, in_progress, completed, canceled)
  • Due dates and time estimates
  • Assignees (multiple users)
  • Parent context
  • Draft/publish versioning

​
Events

Events represent calendar appointments and scheduled activities. Key Properties:
  • Unique ID (UUID)
  • Title, description, and location
  • Start and end timestamps
  • All-day event flag
  • Attendees list with RSVP status
  • Recurrence rules (coming soon)
  • Parent context

​
Contexts

Contexts organize related tasks and events into logical groups. Key Properties:
  • Unique ID (UUID)
  • Name and description
  • Associated tasks and events
  • Collaborators with permissions
  • Sharing settings
  • Activity feed

​
Authentication & Security

​
Access Control

DayCopilot implements database-level access control to ensure data security: What this means for you:
  • You don’t need to filter by user ID in your queries
  • All queries are automatically scoped to the authenticated user
  • Shared resources are handled transparently
  • No risk of accidentally accessing other users’ data
See Access Control & Permissions for detailed information on how data access works.

​
JWT Tokens

All API requests use JSON Web Tokens (JWT) for authentication: 
// Token structure (decoded)
{
  "sub": "user-uuid",
  "email": "user@example.com",
  "role": "authenticated",
  "iat": 1699564800,
  "exp": 1699651200
}

​
API Design Principles

DayCopilot’s API follows REST best practices:

​
Resource-Oriented

GET    /api/v1/tasks          # List tasks
POST   /api/v1/tasks          # Create task
GET    /api/v1/tasks/{id}     # Get specific task
PUT    /api/v1/tasks/{id}     # Update task
DELETE /api/v1/tasks/{id}     # Delete task

​
Consistent Response Format

All successful responses follow this structure: 
{
  "data": { /* resource or array of resources */ },
  "meta": {
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 150
    }
  }
}

​
Predictable Errors

All error responses include: 
{
  "error": "Resource not found",
  "message": "Task with ID abc-123 does not exist",
  "status": 404,
  "correlationId": "req_abc123xyz"
}

​
Draft/Publish Workflow

DayCopilot implements a versioning system for collaborative editing: Key Concepts:
  • version_major: Published version number
  • version_minor: Draft version number
  • is_published: Whether current version is live
  • last_live: Snapshot of last published state

​
Email Processing Flow

When users forward emails to DayCopilot, the platform processes them through an AI pipeline: API Integration Points:
  • Tasks and events created via email appear in the API immediately
  • API-created items don’t trigger email processing
  • You can query email metadata for items created from emails

​
Calendar Integration (CalDAV)

DayCopilot supports bidirectional calendar sync via CalDAV: 
https://app.daycopilot.ai/caldav/
Features:
  • Two-way sync with external calendars
  • RFC 5545 compliant (iCalendar format)
  • Support for recurring events
  • Timezone handling
  • RSVP status tracking

​
Performance & Scalability

​
Caching Strategy

DayCopilot implements intelligent caching:
  • API responses are cacheable (check Cache-Control headers)
  • ETags for conditional requests
  • Pagination for large datasets

​
Rate Limits

See Rate Limits for detailed information on request limits by tier.

​
Pagination

All list endpoints support pagination: 
GET /api/v1/tasks?limit=50&offset=100
Response includes pagination metadata: 
{
  "data": [...],
  "meta": {
    "pagination": {
      "limit": 50,
      "offset": 100,
      "total": 250,
      "hasMore": true
    }
  }
}

​
Integration Patterns

​
Webhooks (Coming Soon)

Subscribe to real-time updates instead of polling: 
// Future webhook payload example
{
  "event": "task.updated",
  "data": {
    "taskId": "123",
    "changes": ["status", "assignees"]
  },
  "timestamp": "2025-11-02T12:00:00Z"
}

​
Batch Operations

For efficiency, batch multiple operations: 
// Create multiple tasks in one request (coming soon)
POST /api/v1/tasks/batch
{
  "tasks": [
    { "title": "Task 1", ... },
    { "title": "Task 2", ... }
  ]
}

​
Best Practices

  • GET for fetching data (never modify)
  • POST for creating resources
  • PUT for full updates
  • PATCH for partial updates
  • DELETE for removing resources
Always check response status codes and handle errors appropriately. Use the correlationId when contacting support for faster troubleshooting.
Monitor X-RateLimit-* headers and implement backoff strategies. Cache responses when possible.
Don’t fetch all records at once. Use limit and offset parameters to paginate through large datasets.
Never expose JWT tokens in client-side code, URLs, or version control. Use environment variables and secure storage.

​
Next Steps

Authentication

Learn about OAuth 2.0 and JWT tokens

API Reference

Explore all available endpoints

Quick Start

Make your first API call

Tasks, Events & Contexts

Understand the core data models