API Best Practices

Guidelines for building reliable, secure, and efficient integrations with the TeamDay API.

Authentication

Token Management

• One token per integration — easier to track and revoke if compromised
• Use environment variables — never hardcode tokens in source code
• Rotate regularly — 30-90 days depending on environment sensitivity
• Revoke immediately if a token is exposed in logs, commits, or error messages

# Good: environment variable
export TEAMDAY_TOKEN="td_your-actual-token-here"

# Bad: hardcoded in script
curl -H "Authorization: Bearer td_AbCdEfGh..."  # Don't do this

Token Security

• Store in environment variables or secret managers (AWS Secrets Manager, Vault, etc.)
• Add .env to .gitignore
• Never log tokens — redact from application logs
• Never send tokens in URL parameters — use the Authorization header only
• Use separate tokens for dev/staging/production

See Authentication docs for token generation and rotation strategies.

Error Handling

Retry Strategy

Retry server errors (5xx) with exponential backoff. Don't retry client errors (4xx) — fix the request instead.

async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options)

    if (response.ok) return response.json()

    // Client errors: don't retry
    if (response.status >= 400 && response.status < 500) {
      const error = await response.json()
      throw new Error(`${response.status}: ${error.message}`)
    }

    // Server errors: retry with backoff
    if (attempt < maxRetries - 1) {
      const delay = Math.pow(2, attempt) * 1000 // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }
  throw new Error('Max retries exceeded')
}

Common Error Codes

See Error Reference for the complete list.

Agent Design

System Prompts

The system prompt is the most important part of your agent. A well-written prompt dramatically improves output quality.

Do:

• Be specific about the agent's role and boundaries
• Include examples of desired output format
• Set clear rules for what the agent should and shouldn't do
• Keep under 2000 characters for best performance

Don't:

• Include API keys or credentials in prompts
• Write vague instructions like "be helpful"
• Overload a single agent with unrelated responsibilities

{
  "systemPrompt": "You are a code review assistant for Python projects.\n\nFor each review:\n1. Check for security vulnerabilities (SQL injection, XSS, etc.)\n2. Flag performance issues\n3. Suggest readability improvements\n\nFormat: use ## Critical, ## Important, ## Minor sections.\nBe specific — reference line numbers and suggest fixes."
}

Agent Granularity

• One agent per domain — a "Code Reviewer" agent, a "Data Analyst" agent
• Reuse agents with different messages rather than creating a new agent per task
• Use Spaces to give the same agent different tools and context for different projects

Naming Conventions

• Use descriptive, action-oriented names: "Python Code Reviewer", "Weekly Analytics Reporter"
• Avoid generic names: "Agent 1", "My Agent", "Test"
• Include the domain or specialty in the name

Execution Patterns

Session Continuity

Pass sessionId from previous responses to continue conversations with full context:

# First message
RESULT=$(curl -s -X POST https://us.teamday.ai/api/v1/agents/$AGENT_ID/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Analyze our Q4 revenue data"}')

SESSION_ID=$(echo $RESULT | jq -r '.sessionId')

# Follow-up with context
curl -X POST https://us.teamday.ai/api/v1/agents/$AGENT_ID/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"message\": \"Now compare with Q3\", \"sessionId\": \"$SESSION_ID\"}"

Space-Scoped Execution

Execute agents within a Space to give them access to tools, files, and secrets:

curl -X POST https://us.teamday.ai/api/v1/agents/$AGENT_ID/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review the latest pull requests",
    "spaceId": "your-space-id"
  }'

The agent will have access to all MCP servers, skills, and secrets configured in that Space.

Scheduling with Missions

Choose the Right Schedule Type

Mission Design

• Clear goals — write goal as a complete instruction the agent can act on independently
• Pair with a Space — set spaceId so the agent has access to tools and context
• Link to a Character — set characterId so the mission uses the right system prompt and model

{
  "title": "Weekly SEO Report",
  "goal": "Analyze this week's search performance. Compare organic traffic, top queries, and ranking changes vs last week. Highlight any pages that dropped more than 5 positions. Save the report as weekly-seo-report.md.",
  "icon": "📊",
  "characterId": "your-agent-id",
  "spaceId": "your-space-id",
  "schedule": { "type": "cron", "value": "0 9 * * 1" }
}

Performance Tips

• Cache responses when appropriate — don't re-execute for the same query
• Use reasonable request rates — stay under 100 requests/minute
• Be specific in messages — vague prompts produce longer, more expensive responses
• Use sessionId for multi-turn conversations instead of repeating context in each message
• Set visibility to private for experimental agents to keep your agent list clean

Security Checklist

Before going to production:

• Tokens stored in environment variables or secret manager
• .env files added to .gitignore
• No credentials in agent system prompts
• Separate tokens for dev/staging/production environments
• Token rotation schedule documented
• Error responses don't leak sensitive information in logs

Related Resources

• Authentication — Token management and security
• API Examples — Quick-start code snippets
• Error Reference — Complete error code documentation
• Code Review Bot — Full tutorial example

Last Updated: February 19, 2026