Tasks, Events & Contexts

Overview

Day Copilot’s data model revolves around three primary entities: Tasks, Events, and Contexts. Understanding how these work together is essential for building effective integrations.

Tasks

Tasks represent actionable items that need to be completed.

Core Properties

Property	Type	Description
`id`	UUID	Unique identifier
`title`	string	Task name (required)
`description`	string	Detailed description
`status`	enum	`pending`, `in_progress`, `completed`, `canceled`
`priority`	enum	`low`, `medium`, `high`, `urgent`
`due_date`	timestamp	When the task is due
`created_at`	timestamp	Creation time
`updated_at`	timestamp	Last modification time
`user_id`	UUID	Owner of the task
`context_id`	UUID	Parent context (optional)

Versioning Properties

Tasks support draft/publish workflows:

Property	Type	Description
`version_major`	integer	Published version number
`version_minor`	integer	Draft version number
`is_published`	boolean	Whether current version is published
`last_live`	jsonb	Snapshot of last published state

Status Lifecycle

Assignees

Tasks can have multiple assignees:

{
  "task_id": "uuid",
  "user_id": "uuid",
  "assigned_at": "2025-11-02T12:00:00Z",
  "assigned_by": "uuid"
}

Example Task Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Complete API documentation",
  "description": "Write comprehensive API docs for REST endpoints",
  "status": "in_progress",
  "priority": "high",
  "due_date": "2025-11-10T17:00:00Z",
  "created_at": "2025-11-02T12:00:00Z",
  "updated_at": "2025-11-02T15:30:00Z",
  "user_id": "user-uuid",
  "context_id": "context-uuid",
  "version_major": 1,
  "version_minor": 1,
  "is_published": true,
  "last_live": null
}

Events

Events represent calendar appointments and scheduled activities.

Core Properties

Property	Type	Description
`id`	UUID	Unique identifier
`title`	string	Event name (required)
`description`	string	Event details
`start_time`	timestamp	Event start (required)
`end_time`	timestamp	Event end (required)
`location`	string	Physical or virtual location
`all_day`	boolean	Whether event is all-day
`created_at`	timestamp	Creation time
`updated_at`	timestamp	Last modification time
`user_id`	UUID	Event organizer
`context_id`	UUID	Parent context (optional)

Attendees

Events can have multiple attendees with RSVP status:

{
  "event_id": "uuid",
  "user_id": "uuid",
  "email": "attendee@example.com",
  "rsvp_status": "accepted",
  "added_at": "2025-11-02T12:00:00Z"
}

RSVP Status Values:

pending - Invitation sent, no response
accepted - Confirmed attendance
declined - Will not attend
tentative - Maybe attending

Example Event Object

{
  "id": "event-uuid",
  "title": "Team Standup",
  "description": "Daily sync meeting",
  "start_time": "2025-11-03T10:00:00Z",
  "end_time": "2025-11-03T10:30:00Z",
  "location": "Zoom: https://zoom.us/j/123456",
  "all_day": false,
  "created_at": "2025-11-02T12:00:00Z",
  "updated_at": "2025-11-02T12:00:00Z",
  "user_id": "user-uuid",
  "context_id": "project-uuid"
}

Contexts

Contexts organize related tasks and events into logical groups (projects, goals, categories).

Core Properties

Property	Type	Description
`id`	UUID	Unique identifier
`name`	string	Context name (required)
`description`	string	Purpose or details
`color`	string	Visual identifier (hex color)
`created_at`	timestamp	Creation time
`updated_at`	timestamp	Last modification time
`user_id`	UUID	Context owner
`parent_context_id`	UUID	Parent context for nesting

Contexts can be shared with other users:

{
  "context_id": "uuid",
  "user_id": "uuid",
  "permission": "read",
  "shared_at": "2025-11-02T12:00:00Z",
  "shared_by": "owner-uuid"
}

Permission Levels:

read - View tasks and events
write - Create and modify items
admin - Full control including sharing

Example Context Object

{
  "id": "context-uuid",
  "name": "Q4 Launch Project",
  "description": "Product launch for Q4 2025",
  "color": "#2a7fff",
  "created_at": "2025-11-01T12:00:00Z",
  "updated_at": "2025-11-02T12:00:00Z",
  "user_id": "user-uuid",
  "parent_context_id": null
}

Relationships

Context Hierarchy

Contexts can be nested to create organizational structures:

Company
├── Engineering
│   ├── API Development
│   └── Frontend Development
└── Marketing
    ├── Content
    └── Social Media

Tasks & Events in Contexts

Tasks and events can belong to a context:

// Task in context
{
  "id": "task-uuid",
  "title": "Design API endpoints",
  "context_id": "api-development-uuid",
  ...
}

// Event in context
{
  "id": "event-uuid",
  "title": "Sprint Planning",
  "context_id": "api-development-uuid",
  ...
}

Querying by Context

Fetch all items in a context:

# Get all tasks in a context
GET /api/v1/tasks?context_id=api-development-uuid

# Get all events in a context
GET /api/v1/events?context_id=api-development-uuid

Comments

Both tasks and events support threaded comments.

Comment Structure

{
  "task_id": "uuid",           // OR event_id
  "message": "Great progress!",
  "created_at": "2025-11-02T12:00:00Z",  // Also serves as ID
  "updated_at": "2025-11-02T12:05:00Z",
  "user_id": "user-uuid"
}

Key Detail: Comments use ISO 8601 timestamps as unique identifiers. This ensures chronological ordering and uniqueness.

Adding Comments

# Add comment to task
POST /api/v1/tasks/{taskId}/comments
{
  "message": "Updated the priority based on feedback"
}

# Add comment to event
POST /api/v1/events/{eventId}/comments
{
  "message": "Location changed to Room B"
}

Email-Generated Content

Tasks and events can be automatically created from forwarded emails.

Email Metadata

Items created from emails include metadata:

{
  "id": "task-uuid",
  "title": "Review contract",
  "source_email_id": "email-uuid",
  "extracted_at": "2025-11-02T12:00:00Z",
  "extraction_confidence": 0.95,
  ...
}

Querying Email-Generated Items

# Get tasks created from emails
GET /api/v1/tasks?source=email

# Get specific email's extracted items
GET /api/v1/tasks?source_email_id=email-uuid

Best Practices

Use Contexts for Organization

Group related tasks and events into contexts for better organization and team collaboration.

Leverage Priority & Status

Use priority to indicate urgency and status to track progress. This enables filtering and smart notifications.

Set Due Dates

Always set due dates on tasks to enable timeline views and deadline reminders.

Use Comments for Collaboration

Add comments instead of modifying descriptions to preserve history and enable discussion.

Nest Contexts Carefully

Avoid deep nesting (max 2-3 levels) to keep organization simple and performant.

Next Steps

Draft/Publish Workflow

Learn about versioning and collaborative editing

Access Control

Understand data access controls and permissions

API Reference

Explore endpoints for tasks, events, and contexts

Managing Tasks Guide

Practical guide to task management

Getting Started

Core Concepts

Guides

Resources

Tasks, Events & Contexts

Overview

Tasks

Core Properties

Versioning Properties

Status Lifecycle

Assignees

Example Task Object

Events

Core Properties

Attendees

Example Event Object

Contexts

Core Properties

Example Context Object

Relationships

Context Hierarchy

Tasks & Events in Contexts

Querying by Context

Comments

Comment Structure

Adding Comments

Email-Generated Content

Email Metadata

Querying Email-Generated Items

Best Practices

Next Steps

Draft/Publish Workflow

Access Control

API Reference

Managing Tasks Guide

Getting Started

Core Concepts

Guides

Resources

​Overview

​Tasks

​Core Properties

​Versioning Properties

​Status Lifecycle

​Assignees

​Example Task Object

​Events

​Core Properties

​Attendees

​Example Event Object

​Contexts

​Core Properties

​Sharing & Collaboration

​Example Context Object

​Relationships

​Context Hierarchy

​Tasks & Events in Contexts

​Querying by Context

​Comments

​Comment Structure

​Adding Comments

​Email-Generated Content

​Email Metadata

​Querying Email-Generated Items

​Best Practices

​Next Steps

Draft/Publish Workflow

Access Control

API Reference

Managing Tasks Guide

Overview

Tasks

Core Properties

Versioning Properties

Status Lifecycle

Assignees

Example Task Object

Events

Core Properties

Attendees

Example Event Object

Contexts

Core Properties

Sharing & Collaboration

Example Context Object

Relationships

Context Hierarchy

Tasks & Events in Contexts

Querying by Context

Comments

Comment Structure

Adding Comments

Email-Generated Content

Email Metadata

Querying Email-Generated Items

Best Practices

Next Steps