Skip to main content

API Reference

The API has 39 route modules organized by domain. All routes are prefixed with /api/v1. Authentication is via Authorization: Bearer <token> header. Request and response bodies use JSON.

Authentication & Users​

RouteMethod(s)EndpointsMiddleware
/api/v1/authPOST, GETregister, login, login/phone, oauth/:provider, otp/send, otp/verify, onboarding, refresh, logout, me, change-password, forgot-password, reset-passwordauthLimiter on login/register
/api/v1/workspacesCRUDCreate, read, update, delete workspaces + members sub-routesauthenticate, requireWorkspace
/api/v1/accountsCRUDSocial account connection and managementauthenticate, requireWorkspace('EDITOR')

Content & Publishing​

RouteMethod(s)EndpointsMiddleware
/api/v1/postsCRUDCreate, read, update, delete + publish, duplicateauthenticate, requireWorkspace('EDITOR'), requireQuota('posts')
/api/v1/schedulesCRUDSchedule management for timed publishingauthenticate, requireWorkspace('EDITOR')
/api/v1/mediaPOST, GET, DELETEFile upload, listing, deletionauthenticate, upload middleware
/api/v1/brand-voiceCRUDBrand voice configuration and trainingauthenticate, requireWorkspace('EDITOR')
/api/v1/repurposePOSTContent repurposing (transform formats)authenticate, requireWorkspace('EDITOR'), requireFeature
/api/v1/calendarsCRUDAI-generated content calendarsauthenticate, requireWorkspace('EDITOR')
/api/v1/trendsGETTrending topic detectionauthenticate, requireWorkspace('VIEWER')

AI​

RouteMethod(s)EndpointsMiddleware
/api/v1/aiPOSTcaption/generate, caption/rewrite, hashtags/generate, cta/generate, translate, image/generateauthenticate, requireWorkspace('EDITOR'), requireQuota('ai_generations'), aiLimiter
/api/v1/ai/chatPOSTAI chat conversationsauthenticate, aiLimiter
/api/v1/ai/suggestionsGETAI-generated content suggestionsauthenticate, requireFeature('ai_suggestions')

Analytics & Intelligence​

RouteMethod(s)EndpointsMiddleware
/api/v1/analyticsGETdashboard, timeseries, timeseries/by-platform, posts/:postId, sync/:publicationIdauthenticate, requireWorkspace('VIEWER')
/api/v1/analytics/ab-testsCRUDA/B test creation, management, and evaluationauthenticate, requireWorkspace('EDITOR')
/api/v1/analytics/advisorGETAI-powered performance recommendationsauthenticate, requireWorkspace('VIEWER')
/api/v1/predictionsGETEngagement and revenue predictionsauthenticate, requireFeature('predictions')
/api/v1/intelligenceGETGap analysis, algorithmic insightsauthenticate, requireWorkspace('VIEWER')
/api/v1/competitorsCRUDCompetitor tracking and snapshotsauthenticate, requireWorkspace('EDITOR')

Conversations (ICE - Intelligent Conversational Engine)​

RouteMethod(s)EndpointsMiddleware
/api/v1/iceGET, POST, PATCHthreads, messages, reply, ai-suggest, resolve, reopenauthenticate, requireWorkspace('EDITOR')
/api/v1/iceGET, PATCHbot-toggle, bot-configauthenticate, requireWorkspace('ADMIN')
/api/v1/iceCRUDescalation-rules, escalationsauthenticate, requireWorkspace('ADMIN')
/api/v1/iceGETexperiments, statsauthenticate, requireWorkspace('VIEWER')
/api/v1/conversationsGETLegacy inbox endpointsauthenticate

E-Commerce & Commerce​

RouteMethod(s)EndpointsMiddleware
/api/v1/ecommercePOST, GETshopify, woocommerce, easyorders (store connection)authenticate, requireWorkspace('ADMIN')
/api/v1/ecommerceGETproducts, templates, syncauthenticate, requireWorkspace('EDITOR')
/api/v1/commerceGETrevenue/dashboard, revenue/posts, orders, segments, couponsauthenticate, requireWorkspace('VIEWER')

Automation & Workflows​

RouteMethod(s)EndpointsMiddleware
/api/v1/workflowsCRUDCreate, read, update, delete workflowsauthenticate, requireWorkspace('EDITOR')
/api/v1/workflowsPOSTactivate, pause, runs, testauthenticate, requireWorkspace('EDITOR')

Ads​

RouteMethod(s)EndpointsMiddleware
/api/v1/adsCRUDAd campaigns, auto-boost rules, performance dataauthenticate, requireWorkspace('EDITOR'), requireFeature('ads')

Audience & CRM​

RouteMethod(s)EndpointsMiddleware
/api/v1/audienceGETAudience profiles, segments, tags, interactionsauthenticate, requireWorkspace('VIEWER')

Agency & Collaboration​

RouteMethod(s)EndpointsMiddleware
/api/v1/approvalsCRUDApproval request workflowsauthenticate, requireWorkspace('EDITOR')
/api/v1/reportsCRUDClient report generationauthenticate, requireWorkspace('EDITOR')

Integrations & Webhooks​

RouteMethod(s)EndpointsMiddleware
/api/v1/integrationsCRUDThird-party integration managementauthenticate, requireWorkspace('ADMIN')
/api/v1/webhooksCRUDWebhook configuration and managementauthenticate, requireWorkspace('ADMIN')

Billing & Payments​

RouteMethod(s)EndpointsMiddleware
/api/v1/paymentsPOSTStripe/Paymob webhook handlersSignature verification
/api/v1/plansGETAvailable subscription plansPublic
/api/v1/usageGETWorkspace usage statisticsauthenticate, requireWorkspace('ADMIN')

Admin (Super Admin)​

RouteMethod(s)EndpointsMiddleware
/api/v1/adminGET, POST, PATCH, DELETEPlatform-wide dashboard, user management, AI usage monitoring, billing managementauthenticate, requireSuperAdmin

Request Validation​

All request bodies are validated using Zod schemas from the @unipulse/shared package via the validate.ts middleware. Invalid requests receive a 400 response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "caption",
        "message": "String must contain at least 1 character(s)"
      }
    ]
  }
}

Rate Limiting​

LimiterScopeLimitRoutes
authLimiterPer IPStrict/api/v1/auth/login, /api/v1/auth/register, /api/v1/auth/otp/*
aiLimiterPer workspacePlan-based/api/v1/ai/*
GlobalPer IPLiberalAll other routes

Standard Error Response​

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Post not found",
    "details": {}
  }
}
CodeHTTP Status
VALIDATION_ERROR400
UNAUTHORIZED401
FORBIDDEN403
NOT_FOUND404
CONFLICT409
RATE_LIMITED429
INTERNAL_ERROR500
Cross-Reference