Quick Start Guide

Get up and running with the Waymaker One API in minutes. This guide will walk you through authentication setup, making your first request, and understanding the response format.

1. Get Your Credentials

For Waymaker App Integration

If you're integrating with an existing Waymaker application, you already have access:

import { createClient } from '@supabase/supabase-js';

// Use your app's existing Supabase client
const supabase = createClient(
  process.env.VITE_SUPABASE_URL!,
  process.env.VITE_SUPABASE_ANON_KEY!
);

// Get the current user's session
const { data: { session } } = await supabase.auth.getSession();
const userToken = session?.access_token;

For External Applications

Register for an API key at api.waymakerone.com/register:

1. Sign up for a developer account
2. Choose your tier (Developer tier is free to start)
3. Generate API key from your dashboard
4. Store securely in environment variables

# Add to your .env file
WAYMAKER_API_KEY=your_api_key_here

2. Make Your First Request

Simple Strategic Question

const response = await fetch('https://api.waymakerone.com/v1/coordinate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token', // or use 'apikey': 'your-api-key'
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: 'What frameworks should I use for strategic planning?'
    }]
  })
});

const result = await response.json();
console.log(result.content);

Framework-Specific Request

const response = await fetch('https://api.waymakerone.com/v1/coordinate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: 'Help me create a Customer Journey Canvas for my e-commerce business'
    }],
    userContext: {
      industry: 'retail',
      businessStage: 'growth',
      role: 'founder'
    },
    preferences: {
      responseStyle: 'detailed',
      forceAgent: 'framework'
    }
  })
});

const result = await response.json();

3. Understand the Response

Basic Response Structure

{
  "content": "# Strategic Planning Framework Recommendations\n\nFor effective strategic planning, I recommend starting with these core frameworks...",
  "metadata": {
    "sessionId": "session_abc123",
    "coordinationStrategy": "single_specialist",
    "agentsInvolved": ["one-framework-expert"],
    "creditsUsed": 5,
    "processingTimeMs": 2100
  },
  "suggestions": {
    "followUpQuestions": [
      "What's your current business stage?",
      "What industry are you in?"
    ],
    "relatedFrameworks": [
      "Strategy Canvas",
      "Business Model Canvas"
    ],
    "nextSteps": [
      "Define your strategic objectives",
      "Assess your current position"
    ]
  }
}

Key Response Fields

Field	Description
content	Main response content (markdown formatted)
metadata.sessionId	Session ID for conversation continuity
metadata.creditsUsed	Credits consumed by this request
metadata.agentsInvolved	Which specialist agents were used
suggestions.followUpQuestions	Suggested next questions
suggestions.relatedFrameworks	Related Waymaker frameworks

4. Continue the Conversation

Use the sessionId from the response to maintain context:

const followUpResponse = await fetch('https://api.waymakerone.com/v1/coordinate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: 'Help me create a Customer Journey Canvas'
      },
      {
        role: 'assistant',
        content: 'I'll help you create a comprehensive Customer Journey Canvas...'
      },
      {
        role: 'user',
        content: 'How do I identify the key touchpoints?'
      }
    ],
    sessionId: 'session_abc123' // Use sessionId from previous response
  })
});

5. Common Use Cases

Strategic Framework Selection

// Get framework recommendations
const request = {
  messages: [{
    role: 'user',
    content: 'We need help with competitive positioning for our SaaS product'
  }],
  userContext: {
    industry: 'software',
    businessStage: 'startup'
  }
};

Expected Response: Strategy Canvas or Competitive Analysis Canvas recommendation with implementation guidance.

Customer Experience Analysis

// Analyze customer experience
const request = {
  messages: [{
    role: 'user',
    content: 'Our customers are churning during onboarding'
  }],
  preferences: {
    forceAgent: 'framework'
  }
};

Expected Response: Customer Journey Canvas with specific onboarding optimization guidance.

Organizational Design

// Get organizational guidance
const request = {
  messages: [{
    role: 'user',
    content: 'We have role clarity issues as we scale our team'
  }],
  userContext: {
    businessStage: 'growth',
    role: 'ceo'
  }
};

Expected Response: Roles Canvas or Employee Journey Canvas with team structure recommendations.

6. Error Handling

Always check the response status and handle errors gracefully:

async function callWaymakerAPI(request) {
  try {
    const response = await fetch('https://api.waymakerone.com/v1/coordinate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-token',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(request)
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          console.error('Authentication failed:', error.message);
          break;
        case 402:
          console.error('Insufficient credits:', error.details);
          break;
        case 429:
          console.error('Rate limited. Retry after:', error.details.resetTime);
          break;
        default:
          console.error('API error:', error.message);
      }
      return null;
    }

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

7. Best Practices

Provide Context

Always include relevant business context for better responses:

const request = {
  messages: [{ role: 'user', content: 'Help with strategic planning' }],
  userContext: {
    industry: 'healthcare',        // Helps with industry-specific guidance
    businessStage: 'growth',       // Affects framework complexity
    role: 'product_manager'        // Tailors advice to your role
  }
};

Use Response Suggestions

Leverage the suggestions in responses for better follow-up:

// Use followUpQuestions for conversation flow
const followUp = result.suggestions.followUpQuestions[0];

// Explore relatedFrameworks for comprehensive planning
const nextFramework = result.suggestions.relatedFrameworks[0];

Monitor Credit Usage

Track credit consumption to optimize usage:

let totalCredits = 0;

function trackCredits(response) {
  totalCredits += response.metadata.creditsUsed;
  console.log(`Credits used: ${response.metadata.creditsUsed}, Total: ${totalCredits}`);
}

8. Next Steps

Explore Advanced Features

• Learn about specific agents - Deep dive into Framework, Research, Data, and Planner agents
• Understand rate limiting - Optimize for your usage tier
• See integration patterns - Best practices for production integration

Get Support

• API Documentation - Complete API reference
• Help Center - User guides and tutorials
• Support - Direct technical support

Stay Updated

• Changelog - Latest API updates and new features
• Status Page - Real-time API status and maintenance notices

Example: Complete Integration

Here's a complete example showing authentication, request, error handling, and conversation flow:

import { createClient } from '@supabase/supabase-js';

class WaymakerAPI {
  private supabase;
  private baseUrl = 'https://api.waymakerone.com';

  constructor() {
    this.supabase = createClient(
      process.env.VITE_SUPABASE_URL!,
      process.env.VITE_SUPABASE_ANON_KEY!
    );
  }

  async coordinate(request: any) {
    try {
      const { data: { session } } = await this.supabase.auth.getSession();
      
      if (!session?.access_token) {
        throw new Error('No authentication session found');
      }

      const response = await fetch(`${this.baseUrl}/v1/coordinate`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${session.access_token}`,
          'Content-Type': 'application/json',
          'x-app-context': 'your-app-name'
        },
        body: JSON.stringify(request)
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API Error: ${error.message}`);
      }

      return await response.json();
    } catch (error) {
      console.error('Waymaker API error:', error);
      throw error;
    }
  }
}

// Usage
const waymaker = new WaymakerAPI();

const response = await waymaker.coordinate({
  messages: [{
    role: 'user',
    content: 'Help me create a strategy canvas for my fintech startup'
  }],
  userContext: {
    industry: 'financial_technology',
    businessStage: 'startup',
    role: 'founder'
  }
});

console.log(response.content);

You're now ready to start building with the Waymaker One API!