YeboLink Routes Deep Dive

Complete reference for all 45+ API endpoints in YeboLink.

Route Files Overview

File	Base Path	Description
auth.routes.ts	/api/v1/auth	Authentication & sessions
messages.routes.ts	/api/v1/messages	Send & manage messages
account.routes.ts	/api/v1/account	Balance, usage, profile
apiKeys.routes.ts	/api/v1/api-keys	API key management
billing.routes.ts	/api/v1/billing	Credit packages & Stripe
contacts.routes.ts	/api/v1/contacts	Contact management
webhooks.routes.ts	/api/v1/webhooks	Webhook configuration
dashboard.routes.ts	/api/dashboard	CEO/Admin dashboard
blog.routes.ts	/api/blog	Autoblogger integration
internal.routes.ts	/internal	Cloud Tasks workers

---

Authentication Routes (/api/v1/auth)

POST /signup

Create a new workspace account.

Field	Type	Required	Notes
email	string	✅	Must be valid email
password	string	✅	Min 4 characters
company_name	string	✅	2-100 characters
phone	string		E.164 format
country	string		ISO 3166-1 alpha-2

Auth: None
Rate Limit: 10 attempts / 15 min (per email)

Response:

{
  "success": true,
  "data": {
    "workspace": { "id": "...", "name": "...", "email": "...", "credits_balance": 0 },
    "token": "eyJhbG...",
    "refreshToken": "a3f2d1...",
    "message": "Account created successfully."
  }
}

---

POST /login

Authenticate and receive tokens.

Field	Type	Required
email	string	✅
password	string	✅

Auth: None
Rate Limit: 10 failed attempts / 15 min

---

GET /me

Get current workspace info.

Auth: JWT (Bearer)

---

POST /refresh

Exchange refresh token for new tokens (rotation).

Field	Type	Required
refreshToken	string	✅

Auth: None

---

POST /logout

Revoke a refresh token.

Field	Type	Required
refreshToken	string

Auth: None

---

POST /logout-all

Revoke all sessions for workspace.

Auth: JWT (Bearer)

---

POST /verify-email

Verify email address.

Field	Type	Required
token	string	✅

---

POST /forgot-password

Request password reset email.

Field	Type	Required
email	string	✅

Rate Limit: 10 attempts / 15 min

---

POST /reset-password

Reset password with token.

Field	Type	Required
token	string	✅
password	string	✅

---

Message Routes (/api/v1/messages)

POST /send

Send a single message.

Field	Type	Required	Notes
to	string	✅	Phone (E.164) or email
channel	string	✅	sms, whatsapp, email, voice, push, web
content	object	✅	See below
from	string		Sender name override
metadata	object		Custom metadata

Content Object:

{
  "text": "Message body",
  "subject": "Email subject (required for email)",
  "html": "HTML content (email only)",
  "from_name": "Sender display name",
  "media_urls": ["https://..."]
}

Auth: JWT or API Key (X-API-Key)
Rate Limit: 300 req/min per workspace

Response:

{
  "success": true,
  "data": {
    "message_id": "uuid",
    "status": "queued",
    "credits_used": 1,
    "created_at": "2024-..."
  }
}

---

POST /bulk

Send messages to multiple recipients.

Field	Type	Required	Notes
recipients	array	✅	[{ to: "...", name: "..." }]
channel	string	✅
content	object	✅	Supports placeholders
from	string

Auth: JWT or API Key
Rate Limit: 50 bulk sends / 5 min

Response:

{
  "success": true,
  "data": {
    "queued": 100,
    "failed": 2,
    "message_ids": ["uuid1", "uuid2", ...]
  }
}

---

GET /

List messages with filters.

Query Param	Type	Notes
channel	string	Filter by channel
status	string	queued, sent, delivered, failed, read
startDate	ISO8601
endDate	ISO8601
page	integer	Default: 1
limit	integer	Default: 50, max: 100

Auth: JWT or API Key

---

GET /:id

Get single message details.

Auth: JWT or API Key

---

GET /usage

Get usage statistics.

Query Param	Type	Notes
startDate	ISO8601	Default: 30 days ago
endDate	ISO8601	Default: now

---

Account Routes (/api/v1/account)

GET /balance

Get current credits balance.

Auth: JWT (Bearer)

---

GET /usage

Get usage stats for period.

---

GET /stats

Get comprehensive stats (messages + billing).

---

GET /profile

Get workspace profile.

---

PATCH /profile

Update workspace profile.

Field	Type	Notes
name	string
phone	string
sms_sender_name	string	AI-verified (Gemini)

---

POST /verify-sender

Check if sender name is allowed.

Field	Type	Required
sender_name	string	✅

---

POST /complete-onboarding

Complete onboarding flow.

Field	Type
company_name	string
industry	string
use_cases	array
monthly_volume	string
phone	string

---

GET /analytics

Get detailed analytics.

Query Param	Type	Notes
timeRange	string	24h, 7d, 30d, 90d

---

API Keys Routes (/api/v1/api-keys)

POST /

Create new API key.

Field	Type	Required	Notes
name	string	✅	2-100 characters
scopes	array		Default: ['send_messages', 'read_messages']

Auth: JWT (Bearer)

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Production Key",
    "key": "ybk_abc123...",
    "key_prefix": "ybk_abc1...",
    "scopes": ["send_messages", "read_messages"],
    "created_at": "...",
    "warning": "Save this key securely. It will not be shown again."
  }
}

---

GET /

List all API keys (without actual keys).

---

DELETE /:id

Deactivate an API key.

---

Billing Routes (/api/v1/billing)

GET /packages

Get available credit packages with pricing.

Query Param	Type	Notes
country	string	ISO code for localized pricing

Auth: Optional (JWT for personalized pricing)

Response:

{
  "success": true,
  "data": {
    "packages": [
      {
        "credits": 125,
        "name": "Starter Pack",
        "stripeCurrency": "usd",
        "stripeAmount": 1000,
        "displayFormatted": "$10",
        "usdFormatted": "$10"
      }
    ],
    "mode": "live",
    "country": "US"
  }
}

---

POST /checkout

Create Stripe checkout session.

Field	Type	Required	Notes
credits	integer	✅	1-100,000

Auth: JWT (Bearer)

Response:

{
  "success": true,
  "data": {
    "session_id": "cs_...",
    "url": "https://checkout.stripe.com/..."
  }
}

---

GET /transactions

Get transaction history.

Query Param	Type	Notes
type	string	purchase, usage, refund, adjustment
startDate	ISO8601
endDate	ISO8601
page	integer
limit	integer

---

POST /webhook

Stripe webhook endpoint.

Auth: Stripe signature verification
Note: Raw body preserved for signature validation

---

Contacts Routes (/api/v1/contacts)

POST /

Create single contact.

Field	Type	Required	Notes
phone	string		E.164 format
email	string
name	string		Max 255 chars
custom_fields	object
tags	array

Auth: JWT (Bearer)

---

POST /bulk

Import multiple contacts.

Field	Type	Required
contacts	array	✅

Each contact: { name, phone, email, country }

---

GET /

List contacts with filters.

Query Param	Type	Notes
search	string	Search name/phone/email
tags	array	Filter by tags
page	integer
limit	integer	Max 100

---

GET /:id

Get single contact.

---

PUT /:id

Update contact.

---

DELETE /:id

Delete contact.

---

Webhooks Routes (/api/v1/webhooks)

POST /

Create webhook endpoint.

Field	Type	Required
url	string	✅
events	array	✅

Events: message.sent, message.delivered, message.failed, message.received, credit.low, credit.depleted

Auth: JWT (Bearer)

Response includes secret (shown once):

{
  "data": {
    "webhook": { ... },
    "secret": "abc123...",
    "warning": "Save this secret securely. It will not be shown again."
  }
}

---

GET /

List webhooks (without secrets).

---

GET /events

Get supported webhook events.

---

GET /:id

Get webhook details.

---

PUT /:id

Update webhook.

Field	Type
url	string
events	array
is_active	boolean

---

DELETE /:id

Delete webhook.

---

GET /:id/deliveries

Get webhook delivery history.

Query Param	Type	Notes
limit	integer	Default: 50, max: 100

---

POST /twilio/status

Twilio status callback (internal).

Auth: Twilio signature verification

---

POST /twilio/inbound

Twilio inbound message callback (internal).

---

Dashboard Routes (/api/dashboard)

Auth: All routes require X-API-Key (CEO_DASHBOARD_API_KEY)

GET /metrics

Platform-wide metrics with trends.

---

GET /workspaces

List all workspaces with stats.

---

GET /workspaces/:id

Full workspace details (messages, transactions, API keys).

---

POST /workspaces/:id/credits

Add credits to workspace.

Field	Type	Required
amount	number	✅
description	string

---

POST /workspaces/:id/deactivate

Deactivate workspace.

---

POST /workspaces/:id/activate

Reactivate workspace.

---

GET /stats

Aggregate platform statistics.

---

Blog Routes (/api/blog)

POST /posts

Create blog post.

Auth: X-API-Key (BLOG_API_KEY)

Field	Type	Required
title	string	✅
slug	string	✅
content	string	✅
excerpt	string
category	string
tags	array
status	string	Default: published
author	string	Default: AI
featured_image	string
published_at	ISO8601

---

GET /posts

List published posts.

Query Param	Type
page	integer
limit	integer
category	string

---

GET /posts/:slug

Get post by slug.

---

Internal Routes (/internal)

Auth: Cloud Tasks header verification

POST /process-message

Process queued message.

Field	Type
messageId	string
workspaceId	string

---

POST /deliver-webhook

Deliver webhook to customer endpoint.

Field	Type
webhookId	string
eventType	string
payload	object

---

POST /update-status

Update message status (from provider callback).

Field	Type
messageId	string
status	string
providerMessageId	string
errorMessage	string
workspaceId	string

---

Root Endpoints

GET /

API info.

{
  "name": "YeboLink API",
  "version": "1.0.0",
  "description": "Customer Communications Platform",
  "documentation": "https://api.yebolink.com/docs"
}

---

GET /health

Health check.

{
  "status": "healthy",
  "timestamp": "2024-...",
  "uptime": 12345.67,
  "environment": "production"
}

---

GET /api-docs

Swagger UI documentation.

---

GET /api-docs.json

OpenAPI JSON spec.