API Documentation | Akievo Developer Docs

Getting Started

The Akievo API allows you to interact with your boards programmatically. You can create tasks, update cards, manage labels, and more—all through simple HTTP requests.

1Get an API Key

Create an API key from your account settings to authenticate requests.

2Make Your First Request

All requests are made to a single endpoint with an action parameter.

POST https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header.

cURL

Authorization: Bearer akievo_your_api_key_here

Keep Your API Key Secure

Never expose your API key in client-side code or public repositories. API keys are shown only once when created—store them securely.

API Key Format

API keys start with akievo_followed by a unique identifier. Example: akievo_abc123xyz789...

Scopes

API keys have scopes that determine what actions they can perform:

read - View boards, lists, cards, and other data
write - Create, update, and delete resources

Rate Limiting

API requests are rate limited to ensure fair usage and protect the service. Each API key is limited to 1,000 requests per hour.

Rate Limit Headers

Every API response includes headers with rate limit information:

X-RateLimit-LimitMaximum requests per hour (1000)

X-RateLimit-RemainingRequests remaining in current window

X-RateLimit-ResetUnix timestamp when the limit resets

Rate Limit Exceeded (429)

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. The Retry-After header indicates when you can retry.

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 45 minutes."
  }
}

Best Practices

Cache responses when possible to reduce API calls
Implement exponential backoff when receiving 429 responses
Use webhooks for real-time updates instead of polling
Batch operations when updating multiple resources

Webhooks

Webhooks allow you to receive real-time notifications when events happen on your boards. Instead of polling the API for changes, configure a webhook endpoint and we'll push events to you.

Payload Format

Every webhook delivery follows this standard format:

JSON

{
  "id": "delivery-uuid",
  "event": "card.created",
  "timestamp": "2026-01-02T12:00:00Z",
  "board_id": "board-uuid",
  "data": {
    "card": {
      "id": "card-uuid",
      "title": "New Task",
      "list_id": "list-uuid"
    },
    "list": {
      "id": "list-uuid",
      "title": "To Do"
    }
  },
  "triggered_by": {
    "id": "user-uuid",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Event Types

Subscribe to specific events or use wildcards. Available events:

Event	Category	Description
`card.created`	Cards	A new card was created
`card.updated`	Cards	Card properties were modified
`card.deleted`	Cards	A card was permanently deleted
`card.moved`	Cards	Card was moved to a different list
`card.completed`	Cards	Card was marked as complete
`card.archived`	Cards	Card was archived
`list.created`	Lists	A new list was created
`list.updated`	Lists	List properties were modified
`list.deleted`	Lists	A list was permanently deleted
`checklist.created`	Checklists	A checklist was added to a card
`checklist.deleted`	Checklists	A checklist was removed from a card
`checklist_item.completed`	Checklists	A checklist item was completed
`comment.created`	Comments	A comment was added to a card
`comment.deleted`	Comments	A comment was deleted
`label.assigned`	Labels	A label was added to a card
`label.unassigned`	Labels	A label was removed from a card
`assignee.added`	Assignees	A user was assigned to a card
`assignee.removed`	Assignees	A user was unassigned from a card
`member.added`	Members	A member joined the board
`member.removed`	Members	A member left the board

HTTP Headers

Every webhook delivery includes these headers:

Header	Description
`Content-Type`	application/json
`X-Webhook-Id`	Unique webhook configuration ID
`X-Webhook-Signature`	HMAC-SHA256 signature (if secret configured)
`X-Webhook-Timestamp`	Unix timestamp of the delivery
`User-Agent`	Akievo-Webhooks/1.0

Signature Verification

If you configure a secret, verify the signature to ensure requests are authentic:

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret, timestamp) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}

// Usage in Express.js
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  if (!verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET, timestamp)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Received event:', req.body.event);
  res.status(200).send('OK');
});

Best Practices

Respond quickly — Return a 2xx status within 30 seconds to avoid timeouts
Implement idempotency — Use the delivery ID to handle duplicate deliveries
Process asynchronously — Queue events for processing instead of blocking
Verify signatures — Always validate the HMAC signature if you configured a secret
Handle retries — Failed deliveries are retried with exponential backoff

Auto-Disable Behavior

Webhooks are automatically disabled after 10 consecutive failures. This protects both your endpoint and our systems. You can re-enable a disabled webhook from the board settings after fixing the issue.

API Reference

Common Examples

Get all cards from a board

JavaScript

const response = await fetch('https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer akievo_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'cards.list',
    params: { boardId: 'your-board-id' }
  })
});

const { data: cards } = await response.json();
console.log(`Found ${cards.length} cards`);

Create a task with labels and due date

JavaScript

const response = await fetch('https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer akievo_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'cards.create',
    params: {
      listId: 'your-list-id',
      title: 'Review Q1 metrics',
      description: '## Goals\n- Review sales figures\n- Prepare presentation',
      priority: 'high',
      due_date: '2026-01-15T00:00:00Z'
    }
  })
});

const { data: card } = await response.json();

// Now assign a label
await fetch('https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer akievo_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'labels.assign',
    params: { cardId: card.id, labelId: 'your-label-id' }
  })
});

Move card to Done and mark complete

Python

import requests

# Move card to Done list
requests.post(
    'https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api',
    headers={'Authorization': 'Bearer akievo_your_api_key'},
    json={
        'action': 'cards.move',
        'params': {
            'cardId': 'your-card-id',
            'listId': 'done-list-id',
            'position': 0
        }
    }
)

# Mark as complete
requests.post(
    'https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api',
    headers={'Authorization': 'Bearer akievo_your_api_key'},
    json={
        'action': 'cards.complete',
        'params': {'cardId': 'your-card-id', 'completed': True}
    }
)

Error Handling

All API responses include a success field. When an error occurs, you'll receive an error object with a code and message.

Error Response Format

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions for this action
`NOT_FOUND`	404	Resource not found
`BAD_REQUEST`	400	Invalid request parameters
`RATE_LIMITED`	429	Too many requests, try again later
`INTERNAL_ERROR`	500	Server error, please try again

Integrations

OpenAPI 3.0 Specification

Download the full API specification for Swagger, Postman, or code generation.

ChatGPT Actions

Connect Akievo to ChatGPT to manage your boards through natural language. Create tasks, update progress, and get summaries—all within ChatGPT.

Setup:

Go to ChatGPT → Settings → Custom GPTs
Add Action with URL: https://akievo.com/.well-known/ai-plugin.json
Use your Akievo API key for authentication

Zapier

Automate your workflow by connecting Akievo to 5,000+ apps. Use webhooks for triggers and the API for actions.

Setup:

Create a webhook in your board settings
Use "Webhooks by Zapier" trigger with your webhook URL
Use "Webhooks by Zapier" action with https://hjxidrapzcpgpovymuze.supabase.co/functions/v1/board-api

Build Your Own Integration

Use the API documented above to build custom integrations with any service. The RESTful design makes it easy to integrate with webhooks, serverless functions, and any programming language.