# Missions API Guide

Create, manage, and trigger missions programmatically via the TeamDay REST API.

# Missions API Guide

Manage missions programmatically using the TeamDay REST API. All endpoints require authentication via a Personal Access Token (PAT).

**Base URL:** `https://cc.teamday.ai/api/v1/missions`

---

## Authentication

All requests require a `Bearer` token:

```bash
-H "Authorization: Bearer $TEAMDAY_API_TOKEN"
```

See [API Keys & Authentication](https://docs.teamday.ai/guides/api-keys) for how to create tokens.

---

## Create a Mission

```
POST /api/v1/missions
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | Yes | Mission title |
| `goal` | string | Yes | Instructions for the agent |
| `icon` | string | No | Emoji icon (default: `🎯`) |
| `spaceId` | string | No | Space to run in |
| `characterId` | string | No | Agent to run as (the agent's ID) |
| `agentType` | string | No | Provider: `claude`, `gemini`, `codex` (default: `claude`) |
| `visibility` | string | No | `private`, `organization`, `public` (default: `private`) |
| `schedule` | object | Yes | Schedule configuration |

### Schedule Object

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | `none`, `once`, `cron`, `continuous` |
| `value` | string | Cron expression (required for `cron` type) |

### Example

```bash
curl -X POST "https://cc.teamday.ai/api/v1/missions" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily Analytics Report",
    "goal": "Pull yesterday Google Analytics data and save a summary to reports/daily/",
    "spaceId": "abc123",
    "characterId": "def456",
    "schedule": {
      "type": "cron",
      "value": "0 8 * * *"
    }
  }'
```

### Response

```json
{
  "success": true,
  "id": "mission-xyz789",
  "title": "Daily Analytics Report",
  "status": "pending",
  "schedule": {
    "type": "cron",
    "value": "0 8 * * *",
    "lastRun": null,
    "nextRun": "2026-02-20T08:00:00.000Z",
    "runCount": 0,
    "maxRuns": null
  }
}
```

---

## Update a Mission

```
PATCH /api/v1/missions/:id
```

### Request Body

All fields are optional. Only provided fields are updated.

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Updated title |
| `goal` | string | Updated instructions |
| `icon` | string | Updated emoji icon |
| `characterId` | string or null | Change or remove agent (the agent's ID; null to unbind) |
| `status` | string | `pending`, `running`, `paused`, `completed`, `failed` |
| `schedule` | object | Updated schedule (partial merge with existing) |

### Examples

**Pause a mission:**

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/missions/mission-xyz789" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'
```

**Change schedule:**

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/missions/mission-xyz789" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "type": "cron",
      "value": "0 9 * * 1-5"
    }
  }'
```

**Update goal and resume:**

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/missions/mission-xyz789" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Updated instructions with more detail...",
    "status": "pending"
  }'
```

### Response

```json
{
  "success": true,
  "id": "mission-xyz789",
  "updated": ["goal", "status"]
}
```

---

## TeamdayAdmin Tool

Missions can also be managed from within a conversation using the TeamdayAdmin MCP tool.

### Create

```json
{
  "action": "createMission",
  "data": {
    "title": "Weekly Report",
    "goal": "Generate the weekly performance report.",
    "spaceId": "abc123",
    "schedule": { "type": "cron", "value": "0 9 * * MON" }
  }
}
```

### Update

```json
{
  "action": "updateMission",
  "resourceId": "mission-xyz789",
  "data": {
    "status": "paused"
  }
}
```

### List

```json
{
  "action": "listMissions"
}
```

### Delete

```json
{
  "action": "deleteMission",
  "resourceId": "mission-xyz789"
}
```

---

## Cron Expression Reference

| Expression | Schedule |
|-----------|----------|
| `0 8 * * *` | Daily at 8:00 AM |
| `0 9 * * MON` | Mondays at 9:00 AM |
| `0 9 * * 1-5` | Weekdays at 9:00 AM |
| `0 */6 * * *` | Every 6 hours |
| `0 9 1 * *` | 1st of each month at 9:00 AM |
| `0 9 1 1,4,7,10 *` | Quarterly (Jan, Apr, Jul, Oct) |
| `*/30 * * * *` | Every 30 minutes |

Format: `minute hour day-of-month month day-of-week`

---

## Error Responses

### Validation Error (400)

```json
{
  "statusCode": 400,
  "message": "Validation error",
  "data": [
    { "path": ["title"], "message": "Required" }
  ]
}
```

### Not Found (404)

```json
{
  "statusCode": 404,
  "message": "Mission not found"
}
```

### Unauthorized (401)

```json
{
  "statusCode": 401,
  "message": "Invalid or expired token"
}
```

### Forbidden (403)

```json
{
  "statusCode": 403,
  "message": "Access denied to this mission"
}
```

---

## Next Steps

- [Missions User Guide](https://docs.teamday.ai/guides/missions-user-guide) — Concepts and examples
- [API Keys & Authentication](https://docs.teamday.ai/guides/api-keys) — Set up API tokens
- [CLI Tool](https://docs.teamday.ai/guides/cli-tool) — Manage missions from the command line