TeamDay API v1 - Overview

The TeamDay API enables developers to programmatically interact with the TeamDay AI platform. Build custom integrations, automate workflows, and manage AI agents through a simple REST API.

Base URL: https://us.teamday.ai/api/v1

Current Status: All tested endpoints operational

---

Quick Start

# 1. Get your API token from Settings → API Access
export TEAMDAY_TOKEN="td_your_token_here"

# 2. Make your first request
curl https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

---

API Groups

The TeamDay v1 API is organized into the following resource groups:

Resource	Description	Endpoints
Authentication	Personal Access Tokens (PAT)	Token management
Agents	Create and manage AI agents	6 endpoints
Executions	Track agent execution history	4 endpoints
Tasks	Manage tasks and workflows	2 endpoints
Errors	Error codes and handling	Reference

---

Authentication

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

Authorization: Bearer td_xxxxx...

Get your token:

1. Log in to TeamDay
2. Navigate to Settings → API Access
3. Click Generate New Token
4. Copy and store securely (shown only once)

Learn more about authentication →

---

Core Concepts

Agents

Agents are AI assistants with customizable system prompts, roles, and capabilities. Create agents to automate tasks, analyze data, or assist with workflows.

Example:

# Create a new agent
curl -X POST https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "role": "Research and analysis",
    "systemPrompt": "You are a research assistant...",
    "visibility": "organization"
  }'

View full agent documentation →

Executions

Executions track when agents run. Each execution captures the full history of messages, tool usage, and results.

Example:

# List recent executions
curl https://us.teamday.ai/api/v1/executions?limit=10 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

View full execution documentation →

Tasks

Tasks represent work items assigned to agents or users. Tasks can be filtered by status, assignee, and workspace.

Example:

# List pending tasks
curl https://us.teamday.ai/api/v1/tasks?status=pending \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

View full task documentation →

---

Response Format

All responses follow a consistent JSON structure with a success wrapper:

Success Response

{
  "success": true,
  "agents": [...],
  "total": 5
}

Or for single-resource responses:

{
  "success": true,
  "agent": {
    "id": "abc123def456",
    "name": "Research Assistant",
    "createdAt": "2025-12-09T12:00:00Z"
  }
}

Error Response

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: name"
}

View error reference →

---

Rate Limits

Currently, the API does not enforce rate limits. This may change in the future. Best practices:

• Use reasonable request rates
• Implement exponential backoff for retries
• Cache responses when appropriate
• Consider webhooks for real-time updates (coming soon)

---

Pagination

List endpoints support pagination through query parameters:

# Get 50 results (default limit)
curl https://us.teamday.ai/api/v1/executions \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Specify custom limit
curl https://us.teamday.ai/api/v1/executions?limit=100 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Parameters:

• limit - Maximum results per request (default: 50)

---

Filtering

Most list endpoints support filtering via query parameters:

# Filter executions by agent
curl "https://us.teamday.ai/api/v1/executions?agentId=abc123def456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Filter tasks by status and space
curl "https://us.teamday.ai/api/v1/tasks?status=pending&spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

See individual endpoint documentation for available filters.

---

Data Types

Timestamps

All timestamps are ISO 8601 strings in UTC:

{
  "createdAt": "2025-12-09T12:00:00Z",
  "updatedAt": "2025-12-09T14:30:00Z"
}

IDs

Most resources use Firestore auto-generated IDs (no prefix). Some resources use structured ID formats:

• Agents, Spaces, Chats: Firestore auto-generated (e.g., abc123def456)
• Execution IDs: exec-{timestamp}-{random} (e.g., exec-1734567890-abc)
• Task IDs: task-{timestamp}-{random} (e.g., task-1734567890-abc)
• Personal Access Tokens: td_ prefix (e.g., td_AbCdEf...)

Visibility

Agents and resources support four visibility levels:

• private - Only visible to creator
• organization - Visible to organization members (default)
• public - Visible to all authenticated users
• unlisted - Accessible via direct link only, not listed in search

---

API Changelog

February 2026

Status:

• All core endpoints operational
• Execute endpoint functional

Authentication:

• PAT token system fully operational
• SHA-256 hash validation
• AES-256-GCM encryption at rest
• Automatic expiration handling (7-365 days)
• OAuth tokens from CLI and JWT tokens also supported

Agent CRUD:

• List agents
• Create agent
• Get agent details
• Update agent
• Delete agent (soft archive)
• Execute agent

---

Support & Community

Documentation:

• API Reference
• Best Practices
• Examples

Need help?

• 📧 Email: support at teamday.ai
• 💬 Discord: Join community
• 🐛 Issues: GitHub

---

Next Steps

1. Get authenticated - Generate your API token
2. Create an agent - Build your first AI assistant
3. View examples - See real-world use cases
4. Learn best practices - Optimize your integration

---

Last Updated: February 19, 2026