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

# API Reference

> Complete REST API documentation for Day Copilot

## Welcome to the Day Copilot API

The Day Copilot API is a REST API that allows you to programmatically manage tasks, events, and contexts. All endpoints are accessed via `https://app.daycopilot.ai/api/v1/` and return JSON responses.

<Card title="Interactive API Playground" icon="play" horizontal>
  All API endpoints in this reference include an interactive playground where you can test requests with your own authentication token.
</Card>

## Base URL

```
https://app.daycopilot.ai/api/v1
```

## Authentication

All API requests require authentication via Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
```

<Card title="Get Started with Authentication" icon="key" href="/authentication">
  Learn how to obtain and use API tokens
</Card>

## API Resources

Day Copilot API is organized around three main resources:

<CardGroup cols={3}>
  <Card title="Tasks" icon="list-check" href="/api-reference/tasks/list">
    Create and manage actionable items with assignments, due dates, and priorities
  </Card>

  <Card title="Events" icon="calendar-days" href="/api-reference/events/list">
    Manage calendar events with attendees, times, and locations
  </Card>

  <Card title="Contexts" icon="folder-tree" href="/api-reference/contexts/list">
    Organize tasks and events into shared workspaces
  </Card>
</CardGroup>

## Request Format

### Headers

All requests should include:

```http theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
```

### Body

Request bodies use JSON format:

```bash theme={null}
curl -X POST "https://app.daycopilot.ai/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Complete API documentation",
    "priority": "high",
    "status": "pending"
  }'
```

## Response Format

### Success Responses

Successful responses return HTTP 200/201 with JSON data:

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete API documentation",
    "priority": "high",
    "status": "pending",
    "createdAt": "2025-11-02T12:00:00Z",
    "updatedAt": "2025-11-02T12:00:00Z"
  }
}
```

### List Responses

List endpoints include pagination metadata:

```json theme={null}
{
  "data": [
    { "id": "...", "title": "..." },
    { "id": "...", "title": "..." }
  ],
  "meta": {
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 150,
      "hasMore": true
    }
  }
}
```

### Error Responses

Errors return appropriate HTTP status codes with details:

```json theme={null}
{
  "error": "Validation Error",
  "message": "Field 'title' is required",
  "status": 400,
  "correlationId": "req_abc123xyz",
  "details": {
    "field": "title",
    "constraint": "required"
  }
}
```

## HTTP Status Codes

| Code  | Description                                      |
| ----- | ------------------------------------------------ |
| `200` | OK - Request successful                          |
| `201` | Created - Resource created successfully          |
| `400` | Bad Request - Invalid parameters or request body |
| `401` | Unauthorized - Missing or invalid authentication |
| `403` | Forbidden - Insufficient permissions             |
| `404` | Not Found - Resource doesn't exist               |
| `422` | Unprocessable Entity - Validation failed         |
| `429` | Too Many Requests - Rate limit exceeded          |
| `500` | Internal Server Error - Something went wrong     |
| `503` | Service Unavailable - Temporary outage           |

## Pagination

List endpoints support pagination via query parameters:

```bash theme={null}
GET /api/v1/tasks?limit=50&offset=100
```

### Parameters

| Parameter | Type    | Default | Description                         |
| --------- | ------- | ------- | ----------------------------------- |
| `limit`   | integer | 50      | Number of items to return (max 100) |
| `offset`  | integer | 0       | Number of items to skip             |

### Response

```json theme={null}
{
  "data": [...],
  "meta": {
    "pagination": {
      "limit": 50,
      "offset": 100,
      "total": 250,
      "hasMore": true
    }
  }
}
```

## Filtering & Searching

### Filter by Context

```bash theme={null}
GET /api/v1/tasks?context_id=550e8400-e29b-41d4-a716-446655440000
```

### Search Tasks

```bash theme={null}
GET /api/v1/tasks/search?q=urgent+meeting
```

### Filter by Status

```bash theme={null}
GET /api/v1/tasks?status=pending,in_progress
```

## Sorting

Sort results using the `sort` parameter:

```bash theme={null}
GET /api/v1/tasks?sort=-created_at,priority
```

* Prefix with `-` for descending order
* Multiple sort fields supported (comma-separated)
* Default: `-created_at`

## Versioning

The API uses URL-based versioning. Current version is `v1`:

```
https://app.daycopilot.ai/api/v1/*
```

Breaking changes will be released under a new version (e.g., `/api/v2/`). We'll provide advance notice and migration guides for version changes.

## Rate Limiting

All endpoints are rate-limited. See [Rate Limits](/rate-limits) for details.

Rate limit information is included in response headers:

```http theme={null}
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699564800
```

## Data Types

### UUIDs

All resource IDs use UUID v4 format:

```json theme={null}
"id": "550e8400-e29b-41d4-a716-446655440000"
```

### Timestamps

All timestamps are ISO 8601 formatted in UTC:

```json theme={null}
"createdAt": "2025-11-02T12:00:00Z"
```

### Enums

Many fields accept only specific values:

```typescript theme={null}
// Task priority
type Priority = "low" | "medium" | "high" | "urgent";

// Task status
type Status = "pending" | "in_progress" | "completed" | "canceled";
```

## Idempotency

POST and PUT requests support idempotency via the `Idempotency-Key` header:

```bash theme={null}
curl -X POST "https://app.daycopilot.ai/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"title": "..."}'
```

Requests with the same idempotency key will return the same response, preventing duplicate resource creation.

## Webhooks (Coming Soon)

Subscribe to real-time events:

```json theme={null}
{
  "url": "https://your-app.com/webhooks/daycopilot",
  "events": ["task.created", "task.updated", "event.created"]
}
```

## OpenAPI Specification

Download the complete OpenAPI 3.0 specification:

<Card title="Download OpenAPI Spec" icon="download" href="https://app.daycopilot.ai/api/v1/docs/openapi.json">
  Use with Postman, Insomnia, or code generators
</Card>

## SDKs & Libraries

Official SDKs (coming soon):

* JavaScript/TypeScript
* Python
* Go

Community SDKs:

* PHP (maintained by community)
* Ruby (maintained by community)

## Getting Help

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Make your first API call in 5 minutes
  </Card>

  <Card title="Architecture Guide" icon="diagram-project" href="/concepts/architecture">
    Understand the system architecture
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@daycopilot.ai">
    Contact our support team
  </Card>

  <Card title="API Status" icon="signal" href="https://status.daycopilot.ai">
    Check API uptime and incidents
  </Card>
</CardGroup>

## API Changelog

Stay up to date with API changes:

<Card title="View Changelog" icon="clock-rotate-left" href="/changelog">
  See recent updates and breaking changes
</Card>