Bot API Overview

Introduction

The Mandraki Bot API lets external integrations interact with your organization’s workspace programmatically. You can create and manage tasks, send messages to channels, list teams and members, browse Drive folders, read calendar events, and receive real-time webhook notifications.

All Bot API endpoints are REST-based, use JSON for request and response bodies, and require a mak_ API token for authentication.

Base URL

All API requests use the following base URL:

https://app.mandraki.cloud/api/v1

Every Bot API endpoint is scoped to an organization. The full path pattern is:

https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/...

Replace {orgId} with your organization’s UUID.

Authentication

Include your API token in the Authorization header using the Bearer scheme:

curl -X GET "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/teams" \
  -H "Authorization: Bearer mak_abc123..."

API tokens use the mak_ prefix followed by a base64url-encoded 256-bit secret. Tokens are generated through the Mandraki settings UI or the service account management API. The raw token value is shown only once at creation time — store it securely.

See Authentication for full details on creating service accounts and tokens.

Request Format

• Content-Type: application/json for all request bodies
• Query parameters: Used for filtering and pagination on GET requests
• Path parameters: Resource IDs are UUIDs embedded in the URL path

Example Request

curl -X POST "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks" \
  -H "Authorization: Bearer mak_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review Q1 report",
    "priority": "high",
    "assigneeId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response Format

All responses return JSON. Successful responses return the requested data directly:

{
  "id": "task-uuid",
  "title": "Review Q1 report",
  "priority": "high",
  "status": "not_started",
  "createdAt": "2026-03-27T10:00:00.000Z"
}

List endpoints wrap results in a named array:

{
  "teams": [
    { "id": "team-uuid", "name": "Engineering" },
    { "id": "team-uuid-2", "name": "Design" }
  ]
}

Error Format

Errors use standard HTTP status codes and return a consistent JSON body:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient scopes",
  "missing": ["tasks:write"]
}

Common Error Codes

Status	Error	Description
400	Bad Request	Invalid request body or missing required fields
401	Unauthorized	Missing, invalid, or expired API token
403	Forbidden	Token lacks required scopes or org access
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Organization Scoping

Every Bot API request is verified against the token’s organization. If the {orgId} in the URL does not match the organization the token was created for, the request is rejected with a 403:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "API token does not have access to this organization"
}

A single API token cannot access multiple organizations. Create separate service accounts and tokens for each organization.

Available Endpoints

Module	Base Path	Scopes
Tasks	/orgs/{orgId}/bot/tasks	tasks:read, tasks:write
Teams	/orgs/{orgId}/bot/teams	teams:read, teams:write
Channels	/orgs/{orgId}/bot/channels	channels:read, messages:write, channels:history
Drive	/orgs/{orgId}/bot/drive	drive:read, drive:write
Calendar	/orgs/{orgId}/bot/calendar	calendar:read
Mail	/orgs/{orgId}/bot/mail	mail:read
Users	/orgs/{orgId}/bot/users	users:read, users:read:email

Rate Limiting

Each API token has a configurable rate limit (default: 1,000 requests per hour, maximum: 10,000). When exceeded, the API returns 429 Too Many Requests. See Rate Limiting for details.

Next Steps

1. Create a service account and API token
2. Understand scopes and permissions
3. Set up webhooks for real-time event notifications