TeamDay Mission API - Developer Guide

Overview

The TeamDay Mission API allows you to programmatically create, manage, and trigger automated missions using Personal Access Tokens (PATs) for authentication.

Base URL: https://agent.teamday.ai/api/missions

Authentication

All API requests require a Personal Access Token (PAT) passed in the Authorization header:

Authorization: Bearer YOUR_PAT_TOKEN

Getting Your PAT

1. Log in to TeamDay
2. Go to Settings → API Tokens
3. Click Create New Token
4. Give it a descriptive name (e.g., "CI/CD Automation")
5. Copy the token immediately - it will only be shown once!

Quick Start

Create Your First Mission

curl -X POST https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily Team Summary",
    "instructions": "Generate a summary of yesterday'\''s activity",
    "schedule": {
      "type": "daily",
      "startDate": {"_seconds": 1738310400},
      "timeSpecs": [{"hour": 9, "minute": 0, "second": 0}]
    },
    "isActive": true
  }'

Response:

{
  "success": true,
  "mission": {
    "id": "mission_abc123",
    "title": "Daily Team Summary",
    "isActive": true,
    "nextRunAt": {"_seconds": 1738483200}
  },
  "message": "Mission created successfully"
}

API Endpoints

1. List All Missions

Get all missions in your organization.

GET /api/missions

Example:

curl https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

Response:

{
  "success": true,
  "missions": [
    {
      "id": "mission_abc123",
      "title": "Daily Team Summary",
      "instructions": "Generate a summary...",
      "schedule": {...},
      "isActive": true,
      "nextRunAt": {"_seconds": 1738483200}
    }
  ]
}

2. Get Mission by ID

Retrieve a specific mission.

GET /api/missions/:missionId

Example:

curl https://agent.teamday.ai/api/missions/mission_abc123 \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

3. Create Mission

Create a new automated mission.

POST /api/missions

Request Body:

{
  "title": "string (required)",
  "instructions": "string (required)",
  "schedule": {
    "type": "daily|weekly|monthly|custom",
    "startDate": {"_seconds": number},
    "timeSpecs": [{"hour": number, "minute": number, "second": number}]
  },
  "isActive": boolean (default: true),
  "model": "string (optional)",
  "tools": ["string"] (optional)
}

Schedule Types:

Daily

Runs every day at specified time(s):

{
  "type": "daily",
  "startDate": {"_seconds": 1738310400},
  "timeSpecs": [
    {"hour": 9, "minute": 0, "second": 0}
  ]
}

Weekly

Runs on specific days of the week:

{
  "type": "weekly",
  "startDate": {"_seconds": 1738310400},
  "timeSpecs": [{"hour": 9, "minute": 0}],
  "daysOfWeek": [1, 3, 5]  // Monday, Wednesday, Friday (0=Sunday)
}

Monthly

Runs on a specific day of each month:

{
  "type": "monthly",
  "startDate": {"_seconds": 1738310400},
  "timeSpecs": [{"hour": 9, "minute": 0}],
  "dayOfMonth": 1  // 1st of each month
}

Custom (Cron)

Use cron expressions for advanced scheduling:

{
  "type": "custom",
  "startDate": {"_seconds": 1738310400},
  "cronExpression": "0 9 * * 1-5",  // 9am, Monday-Friday
  "timeSpecs": []
}

Example:

curl -X POST https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Report",
    "instructions": "Compile weekly metrics and send to team",
    "schedule": {
      "type": "weekly",
      "startDate": {"_seconds": '$(date +%s)'},
      "timeSpecs": [{"hour": 10, "minute": 0}],
      "daysOfWeek": [5]
    },
    "isActive": true
  }'

4. Update Mission

Modify an existing mission.

PUT /api/missions/:missionId

Request Body (all fields optional):

{
  "title": "string",
  "instructions": "string",
  "schedule": {...},
  "isActive": boolean
}

Example:

curl -X PUT https://agent.teamday.ai/api/missions/mission_abc123 \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

5. Delete Mission

Archive a mission (soft delete).

DELETE /api/missions/:missionId

Example:

curl -X DELETE https://agent.teamday.ai/api/missions/mission_abc123 \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

6. Trigger Mission Manually

Run a mission immediately, outside of its schedule.

POST /api/missions/:missionId/trigger

Example:

curl -X POST https://agent.teamday.ai/api/missions/mission_abc123/trigger \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

Use Cases:

• Test a mission before scheduling it
• Trigger on-demand reports
• Integrate with external systems (webhooks, CI/CD)

7. Get Mission Execution Logs

View execution history and results.

GET /api/missions/:missionId/logs

Example:

curl https://agent.teamday.ai/api/missions/mission_abc123/logs \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

Response:

{
  "success": true,
  "logs": [
    {
      "id": "log_xyz789",
      "missionId": "mission_abc123",
      "triggeredAt": {"_seconds": 1738483200},
      "status": "success",
      "completedAt": {"_seconds": 1738483265}
    }
  ]
}

Error Handling

Error Response Format

{
  "success": false,
  "error": "Error message",
  "details": [...] // Optional validation errors
}

HTTP Status Codes

Validation Errors

When validation fails (400 response):

{
  "success": false,
  "error": "Validation error",
  "details": [
    {
      "path": ["title"],
      "message": "Title is required"
    }
  ]
}

SDK Examples

JavaScript/TypeScript

class TeamDayMissionAPI {
    constructor(private apiKey: string) {}

    private async request(endpoint: string, options: RequestInit = {}) {
        const response = await fetch(
            `https://agent.teamday.ai/api/missions${endpoint}`,
            {
                ...options,
                headers: {
                    'Authorization': `Bearer ${this.apiKey}`,
                    'Content-Type': 'application/json',
                    ...options.headers,
                },
            }
        );

        const data = await response.json();

        if (!response.ok) {
            throw new Error(data.error || 'API request failed');
        }

        return data;
    }

    async listMissions() {
        return this.request('');
    }

    async createMission(mission: {
        title: string;
        instructions: string;
        schedule: any;
        isActive?: boolean;
    }) {
        return this.request('', {
            method: 'POST',
            body: JSON.stringify(mission),
        });
    }

    async triggerMission(missionId: string) {
        return this.request(`/${missionId}/trigger`, {
            method: 'POST',
        });
    }

    async getMissionLogs(missionId: string) {
        return this.request(`/${missionId}/logs`);
    }
}

// Usage
const api = new TeamDayMissionAPI('YOUR_PAT_TOKEN');

const missions = await api.listMissions();
console.log('My missions:', missions);

const newMission = await api.createMission({
    title: 'Daily Standup Reminder',
    instructions: 'Send standup reminder to Slack',
    schedule: {
        type: 'daily',
        startDate: { _seconds: Math.floor(Date.now() / 1000) },
        timeSpecs: [{ hour: 9, minute: 0, second: 0 }]
    },
    isActive: true
});
console.log('Created:', newMission);

Python

import requests
from datetime import datetime

class TeamDayMissionAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://agent.teamday.ai/api/missions'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def list_missions(self):
        response = requests.get(self.base_url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_mission(self, mission: dict):
        response = requests.post(
            self.base_url,
            headers=self.headers,
            json=mission
        )
        response.raise_for_status()
        return response.json()

    def trigger_mission(self, mission_id: str):
        response = requests.post(
            f'{self.base_url}/{mission_id}/trigger',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
api = TeamDayMissionAPI('YOUR_PAT_TOKEN')

missions = api.list_missions()
print('My missions:', missions)

new_mission = api.create_mission({
    'title': 'Weekly Team Report',
    'instructions': 'Generate weekly team metrics',
    'schedule': {
        'type': 'weekly',
        'startDate': {'_seconds': int(datetime.now().timestamp())},
        'timeSpecs': [{'hour': 10, 'minute': 0}],
        'daysOfWeek': [5]  # Friday
    },
    'isActive': True
})
print('Created:', new_mission)

Common Use Cases

1. CI/CD Integration

Trigger missions after deployments:

# .github/missions/deploy.yml
- name: Trigger Deployment Summary
  run: |
    curl -X POST \
      -H "Authorization: Bearer ${{ secrets.TEAMDAY_PAT }}" \
      https://agent.teamday.ai/api/missions/$WORKFLOW_ID/trigger

2. Scheduled Reports

# Create a mission that runs every Monday at 9 AM
curl -X POST https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer $TEAMDAY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Sales Report",
    "instructions": "Compile sales data from last week and email to team",
    "schedule": {
      "type": "weekly",
      "startDate": {"_seconds": '$(date +%s)'},
      "timeSpecs": [{"hour": 9, "minute": 0}],
      "daysOfWeek": [1]
    },
    "isActive": true
  }'

3. Webhook Automation

// Express.js webhook handler
app.post('/webhook/new-customer', async (req, res) => {
    const customer = req.body;

    await fetch('https://agent.teamday.ai/api/missions', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${process.env.TEAMDAY_PAT}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            title: `Onboarding: ${customer.name}`,
            instructions: `Send onboarding email to ${customer.email}`,
            schedule: {
                type: 'daily',
                startDate: { _seconds: Math.floor(Date.now() / 1000) + 3600 },
                timeSpecs: [{ hour: 10, minute: 0 }]
            },
            isActive: true
        })
    });

    res.json({ success: true });
});

Best Practices

Security

1. Never commit PATs to version control

   # Use environment variables
   export TEAMDAY_PAT="your_token_here"
   

2. Rotate tokens regularly
   • Create new token
   • Update applications
   • Revoke old token
3. Use separate tokens per application
   • Easier to track usage
   • Revoke individual apps without affecting others

Scheduling

1. Use Unix timestamps for startDate

   const startDate = { _seconds: Math.floor(Date.now() / 1000) };
   

2. Test missions before scheduling
   • Create with isActive: false
   • Use /trigger endpoint to test
   • Activate when ready
3. Set appropriate time zones
   • All times are in UTC by default
   • Account for daylight saving time

Error Handling

async function createMissionSafely(mission) {
    try {
        const response = await fetch('https://agent.teamday.ai/api/missions', {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${process.env.TEAMDAY_PAT}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(mission)
        });

        if (!response.ok) {
            const error = await response.json();
            console.error('Failed to create mission:', error);

            if (error.details) {
                // Handle validation errors
                error.details.forEach(detail => {
                    console.error(`${detail.path.join('.')}: ${detail.message}`);
                });
            }

            return null;
        }

        return await response.json();
    } catch (error) {
        console.error('Network error:', error);
        return null;
    }
}

Troubleshooting

401 Unauthorized

Problem: Invalid or missing PAT

Solutions:

• Check that Authorization header is included
• Verify token format: Bearer YOUR_TOKEN
• Ensure token hasn't expired
• Check token is for correct organization

400 Bad Request

Problem: Invalid request format

Solutions:

• Validate JSON syntax
• Check required fields are present
• Verify schedule format matches type
• Review error details in response

500 Internal Server Error

Problem: Server-side error

Solutions:

• Check mission instructions are valid
• Retry request after a moment
• Contact support if persists

Support

• API Status: https://status.teamday.ai
• Support Email: [email protected]
• Documentation: /docs

Changelog

v1.0.0 (2025-10-04)

• Initial release
• PAT-based authentication
• Full CRUD operations for missions
• Manual trigger endpoint
• Execution logs endpoint
• Secure hash-based PAT validation