REST API Reference

This page documents the Cordia REST API endpoints that the SDK communicates with. You can also use these endpoints directly if you prefer not to use the SDK.

ℹ️Base URL

Production: https://api.cordialane.com/api/v1
Development: https://cordlane-brain.onrender.com/api/v1

Authentication

All API requests require authentication via a Bearer token in the Authorization header:

Authentication header

bash

Authorization: Bearer YOUR_API_KEY
X-Bot-Id: YOUR_BOT_ID
Content-Type: application/json

POST /heartbeat

Send a heartbeat ping for uptime monitoring.

Request Body

Request

json

{
  "botId": "your-bot-id",
  "timestamp": "2026-04-06T12:00:00.000Z",
  "uptime": 3600000
}

Response

Response (200 OK)

json

{
  "success": true,
  "message": "Heartbeat received"
}

Field	Type	Required	Description
`botId`	`string`	✅	Your bot's unique ID
`timestamp`	`string`	✅	ISO 8601 timestamp
`uptime`	`number`	✅	Bot uptime in milliseconds

POST /guild-count

Report the bot's current guild/server count.

Request Body

Request

json

{
  "botId": "your-bot-id",
  "count": 150,
  "timestamp": "2026-04-06T12:00:00.000Z"
}

Response

Response (200 OK)

json

{
  "success": true,
  "message": "Guild count updated"
}

Field	Type	Required	Description
`botId`	`string`	✅	Your bot's unique ID
`count`	`number`	✅	Current number of guilds (>= 0)
`timestamp`	`string`	✅	ISO 8601 timestamp

POST /track-command

Track a command execution event.

Request Body

Request

json

{
  "botId": "your-bot-id",
  "event": "command_used",
  "command": "play",
  "userId": "123456789",
  "guildId": "987654321",
  "metadata": {
    "query": "lofi beats"
  },
  "timestamp": "2026-04-06T12:00:00.000Z"
}

Response

Response (200 OK)

json

{
  "success": true,
  "message": "Event tracked"
}

Field	Type	Required	Description
`botId`	`string`	✅	Your bot's unique ID
`event`	`string`	✅	Event type (`"command_used"`)
`command`	`string`	✅	Command name
`userId`	`string`	No	Discord user ID
`guildId`	`string`	No	Guild/server ID
`metadata`	`object`	No	Additional metadata
`timestamp`	`string`	✅	ISO 8601 timestamp

POST /track-user

Track an active user interaction.

Request Body

Request

json

{
  "botId": "your-bot-id",
  "event": "user_active",
  "userId": "123456789",
  "guildId": "987654321",
  "action": "message",
  "timestamp": "2026-04-06T12:00:00.000Z"
}

Response

Response (200 OK)

json

{
  "success": true,
  "message": "Event tracked"
}

Field	Type	Required	Description
`botId`	`string`	✅	Your bot's unique ID
`event`	`string`	✅	Event type (`"user_active"`)
`userId`	`string`	✅	Discord user ID
`guildId`	`string`	No	Guild/server ID
`action`	`string`	No	Action type (default: "interaction")
`timestamp`	`string`	✅	ISO 8601 timestamp

Error Responses

All endpoints may return the following error responses:

401 Unauthorized

json

{
  "success": false,
  "error": "Invalid or missing API key"
}

400 Bad Request

json

{
  "success": false,
  "error": "Missing required field: botId"
}

429 Too Many Requests

json

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

500 Internal Server Error

json

{
  "success": false,
  "error": "Internal server error"
}

💡SDK Handles Errors

The Cordia SDK handles all error cases automatically — including retries with exponential backoff for 5xx and 429 errors. You don't need to implement error handling yourself unless you're using the API directly.

Heartbeat & Uptime