API Documentation

Getting Started

Welcome to the Whama API! This guide will help you get started with integrating Whama into your applications.

Base URL

https://api.whama.co

Response Format

All API responses are returned in JSON format with a consistent structure:

// Successful response
{
  "success": true,
  "data": { /* Response data */ },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Authentication

Whama API supports two authentication methods: API Keys and OAuth 2.0.

API Key Authentication

API keys are the simplest way to authenticate. Include your API key in theX-API-Keyheader with each request.

// Using API Key authentication
const response = await fetch('https://api.whama.co/v1/tasks', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_your_api_key_here',
    'Content-Type': 'application/json',
  },
});

const { data, meta } = await response.json();
console.log('Tasks:', data);

Test vs Live Keys

OAuth 2.0

Use OAuth 2.0 when you need to access Whama on behalf of users. We support the Authorization Code flow with PKCE.

Authorization Flow

1. 1

   Redirect user to authorization URL

   https://whama.co/oauth/authorize?
     client_id=YOUR_CLIENT_ID
     &redirect_uri=https://yourapp.com/callback
     &response_type=code
     &scope=tasks:read tasks:write boards:read
     &state=random_state_string
     &code_challenge=PKCE_CHALLENGE
     &code_challenge_method=S256

2. 2

   User grants permission

   User is redirected back to your app with an authorization code

3. 3

   Exchange code for tokens

   POST /oauth/token
   Content-Type: application/json
   
   {
     "grant_type": "authorization_code",
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "code": "AUTHORIZATION_CODE",
     "redirect_uri": "https://yourapp.com/callback",
     "code_verifier": "PKCE_VERIFIER"
   }

4. 4

   Use access token

   // Using OAuth 2.0 access token
   const response = await fetch('https://api.whama.co/v1/tasks', {
     method: 'GET',
     headers: {
       'Authorization': 'Bearer your_access_token_here',
       'Content-Type': 'application/json',
     },
   });
   
   const { data, meta } = await response.json();
   console.log('Tasks:', data);

Available Scopes

API Endpoints

Below is a reference of all available API endpoints.

Example: Create a Task

// Create a new task
const response = await fetch('https://api.whama.co/v1/tasks', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Review quarterly report',
    description: 'Review and approve Q4 financial report',
    boardId: 'board_abc123',
    columnId: 'column_todo',
    priority: 'high',
    dueDate: '2024-02-15T10:00:00Z',
    labels: ['urgent', 'finance'],
  }),
});

const { data } = await response.json();
console.log('Created task:', data.id);

Pagination

List endpoints support pagination with the following query parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 20, max: 100)
• sort - Field to sort by
• order - Sort order (asc/desc)

// Pagination example
const response = await fetch(
  'https://api.whama.co/v1/tasks?page=1&limit=20&sort=createdAt&order=desc',
  {
    headers: {
      'X-API-Key': 'sk_live_your_api_key_here',
    },
  }
);

const { data, meta } = await response.json();
console.log('Tasks:', data);
console.log('Total:', meta.total);
console.log('Page:', meta.page);
console.log('Total Pages:', meta.totalPages);

Webhooks

Webhooks allow you to receive real-time notifications when events occur in Whama.

Available Events

Payload Format & Verification

Each webhook includes a signature in the X-Webhook-Signature header. Always verify this signature to ensure the webhook is authentic.

// Webhook payload example
{
  "id": "evt_abc123",
  "type": "task.created",
  "createdAt": "2024-01-15T10:30:00Z",
  "data": {
    "task": {
      "id": "task_xyz789",
      "title": "New task",
      "boardId": "board_abc123",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Error Handling

The API uses standard HTTP status codes and returns detailed error information.

HTTP Status Codes

Error Response Format

// Error response format
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  }
}

// Handle errors in your code
const response = await fetch('https://api.whama.co/v1/tasks', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* ... */ }),
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.error.message);
  // Handle specific error codes
  if (error.error.code === 'RATE_LIMIT_EXCEEDED') {
    // Wait and retry
  }
}

Rate Limiting

Rate limits are applied per API key. Check the response headers for limit info:

• X-RateLimit-Limit - Requests allowed per window
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - Unix timestamp when limit resets