> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daycopilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks, Events & Contexts

> Understanding Day Copilot's core data models and their relationships

## 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.

```mermaid theme={null}
graph LR
    CONTEXT[Context] --> TASKS[Tasks]
    CONTEXT --> EVENTS[Events]
    USER[User] --> CONTEXT
    USER --> TASKS
    USER --> EVENTS
    TASKS --> ASSIGNEES[Assignees]
    TASKS --> COMMENTS[Comments]
    EVENTS --> ATTENDEES[Attendees]
    EVENTS --> COMMENTS2[Comments]
```

## 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending
    pending --> in_progress
    pending --> canceled
    in_progress --> completed
    in_progress --> canceled
    in_progress --> pending
    completed --> [*]
    canceled --> [*]
```

### Assignees

Tasks can have multiple assignees:

```json theme={null}
{
  "task_id": "uuid",
  "user_id": "uuid",
  "assigned_at": "2025-11-02T12:00:00Z",
  "assigned_by": "uuid"
}
```

### Example Task Object

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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    |

### Sharing & Collaboration

Contexts can be shared with other users:

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json theme={null}
// 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:

```bash theme={null}
# 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

```json theme={null}
{
  "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

```bash theme={null}
# 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:

```json theme={null}
{
  "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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Use Contexts for Organization">
    Group related tasks and events into contexts for better organization and team collaboration.
  </Accordion>

  <Accordion title="Leverage Priority & Status">
    Use priority to indicate urgency and status to track progress. This enables filtering and smart notifications.
  </Accordion>

  <Accordion title="Set Due Dates">
    Always set due dates on tasks to enable timeline views and deadline reminders.
  </Accordion>

  <Accordion title="Use Comments for Collaboration">
    Add comments instead of modifying descriptions to preserve history and enable discussion.
  </Accordion>

  <Accordion title="Nest Contexts Carefully">
    Avoid deep nesting (max 2-3 levels) to keep organization simple and performant.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Draft/Publish Workflow" icon="code-branch" href="/concepts/draft-workflow">
    Learn about versioning and collaborative editing
  </Card>

  <Card title="Access Control" icon="shield" href="/concepts/access-control">
    Understand data access controls and permissions
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore endpoints for tasks, events, and contexts
  </Card>

  <Card title="Managing Tasks Guide" icon="list-check" href="/guides/managing-tasks">
    Practical guide to task management
  </Card>
</CardGroup>