API Examples

Practical examples for common TeamDay API workflows. All examples use curl with a Personal Access Token.

Setup:

export TEAMDAY_TOKEN="td_your-actual-token-here"

Create and Execute an Agent

The most common workflow: create an agent with a system prompt, then send it a message.

# 1. Create the 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 summarization",
    "systemPrompt": "You are a research assistant. Analyze topics thoroughly and provide concise summaries with key findings.",
    "visibility": "organization"
  }'

# Response:
# { "success": true, "id": "rT4kM8nXwQ2p", "name": "Research Assistant", "status": "active", "chatUrl": "/agents/rT4kM8nXwQ2p/chat" }

# 2. Execute with a message
curl -X POST https://us.teamday.ai/api/v1/agents/rT4kM8nXwQ2p/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the key differences between REST and GraphQL APIs"
  }'

# Response:
# { "success": true, "executionId": "exec-1708300000-abc", "chatId": "agent-rT4kM8nXwQ2p-1708300000", "sessionId": "session-1708300000", "result": "Here are the key differences..." }

Continue a Conversation

Pass sessionId from a previous execution to continue the conversation with context:

curl -X POST https://us.teamday.ai/api/v1/agents/rT4kM8nXwQ2p/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Now compare their performance characteristics",
    "sessionId": "session-1708300000"
  }'

Execute in a Space

Run the agent in a specific Space so it has access to files, MCP servers, and secrets configured there:

curl -X POST https://us.teamday.ai/api/v1/agents/rT4kM8nXwQ2p/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze the codebase and suggest improvements",
    "spaceId": "kf8x2mNp4qRt"
  }'

Set Up a Space with Tools

Create a space, add secrets, configure an MCP server, and wire everything together:

# 1. Create a space
curl -X POST https://us.teamday.ai/api/v1/spaces \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Analysis Workspace"
  }'
# Response: { "success": true, "id": "kf8x2mNp4qRt", ... }

# 2. Store API keys as encrypted secrets
curl -X POST https://us.teamday.ai/api/v1/spaces/kf8x2mNp4qRt/secrets \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": {
      "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
    }
  }'
# Response: { "success": true, "message": "Stored 1 secret(s)", "keys": ["GITHUB_TOKEN"] }

# 3. Create an MCP server instance
curl -X POST https://us.teamday.ai/api/v1/mcps \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mcpType": "github",
    "name": "GitHub Integration",
    "credentials": {
      "GITHUB_TOKEN": { "value": "ghp_xxxxxxxxxxxx", "isSecret": true }
    }
  }'
# Response: { "success": true, "id": "mcp123abc", "name": "GitHub Integration", "mcpType": "github" }

# 4. Add agent and MCP to the space
curl -X PATCH https://us.teamday.ai/api/v1/spaces/kf8x2mNp4qRt \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addAgents": ["rT4kM8nXwQ2p"],
    "addMcps": ["mcp123abc"]
  }'

Schedule a Recurring Mission

Create a mission that runs your agent on a cron schedule:

# Daily report at 9 AM UTC
curl -X POST https://us.teamday.ai/api/v1/missions \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily Code Review",
    "goal": "Review all open pull requests and summarize findings",
    "icon": "🔍",
    "characterId": "rT4kM8nXwQ2p",
    "spaceId": "kf8x2mNp4qRt",
    "schedule": {
      "type": "cron",
      "value": "0 9 * * *"
    }
  }'

# Response:
# { "success": true, "id": "mission123", "title": "Daily Code Review", "status": "pending", "schedule": { "type": "cron", "value": "0 9 * * *", "nextRun": "2026-02-20T09:00:00Z", "runCount": 0 } }

Common cron schedules:

  • 0 9 * * * — Every day at 9 AM UTC
  • 0 9 * * 1-5 — Weekdays at 9 AM UTC
  • 0 9 * * 1 — Every Monday at 9 AM UTC
  • 0 */6 * * * — Every 6 hours

List and Filter Executions

Track what your agents have been doing:

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

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

# Get execution details with full message tree
curl https://us.teamday.ai/api/v1/executions/exec-1708300000-abc/tree \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Error Handling in Code

A JavaScript/TypeScript pattern for robust API calls:

const TEAMDAY_TOKEN = process.env.TEAMDAY_TOKEN

async function executeAgent(agentId, message, options = {}) {
  const response = await fetch(
    `https://us.teamday.ai/api/v1/agents/${agentId}/execute`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${TEAMDAY_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ message, ...options }),
    }
  )

  if (!response.ok) {
    const error = await response.json()

    // Don't retry client errors (4xx)
    if (response.status >= 400 && response.status < 500) {
      throw new Error(`Client error: ${error.message}`)
    }

    // Retry server errors (5xx) with backoff
    throw new Error(`Server error: ${error.message}`)
  }

  return response.json()
}

// Usage
const result = await executeAgent('rT4kM8nXwQ2p', 'Analyze this dataset', {
  spaceId: 'kf8x2mNp4qRt',
})
console.log(result.result)

Full Tutorials

For complete end-to-end walkthroughs, see:

Last Updated: February 19, 2026