Pegacraft
PlatformDevelopers

API overview

REST endpoints by module. Every route below sits behind JwtAuthGuard unless noted.

Hand-maintained, not generated

There's no OpenAPI spec behind this page. It's a direct reflection of the NestJS controllers. Treat the controller source as the final word if this drifts.

Every route sits behind JwtAuthGuard. Mutating routes on Accounts, Configs, and Reply Manage additionally sit behind RolesGuard, requiring owner or manager (mentions' approve/dismiss also accept moderator). See Projects and roles and Multi-tenancy for how a role is resolved and enforced.

Auth

MethodPathNotes
POST/auth/loginNo guard. Returns a JWT carrying { sub, tenantId, role }. No signup or refresh flow.
GET/auth/meThe decoded identity of the current token.
GET/auth/tenantsEvery project the caller belongs to, with their role in each. Powers the project switcher.
POST/auth/tenantsCreates a new project; the caller becomes its owner and gets back a JWT scoped to it.
POST/auth/switch-tenantRe-issues a JWT scoped to a project the caller already has a membership in. 403 otherwise.

Accounts

MethodPathNotes
GET/accountsList accounts for the current tenant.
POST/accountsCreate a channel row. Requires riskAcknowledged: true for browser_session connections.
GET/accounts/:id
PATCH/accounts/:id
DELETE/accounts/:idAlso unschedules any recurring mention-scrape job for the account.
POST/accounts/:id/secretStore the encrypted session/bot credential.
POST/accounts/:id/verifyRuns a live check against the platform, flips status to active on success.
GET/accounts/:id/topic-performanceSee The loop.
GET/accounts/:id/metrics-timeseries?days=7|30Zero-filled daily series behind Analytics, each point carrying a score (0-100 percentile rank against the account's trailing 90-day baseline, or null on a day with no impressions).

Posts and publishing

MethodPathNotes
GET/postsFilterable by status, accountId, and a date range.
POST/posts/:id/approveMoves pending_approval → scheduled.
PATCH/posts/:id/bodyEdits the body. Draft/pending/scheduled posts are a plain DB update; a posted Telegram or Discord post is edited live through the adapter (X and manual platforms reject with a clear message). Response includes live: boolean.
POST/posts/:id/rejectBody includes a rejection reason. See Review queue.
POST/posts/:id/publishPublish now, skipping the schedule.
PATCH/posts/:id/scheduleReschedule; replaces rather than duplicates the pending publish job.
PATCH/posts/:id/mark-postedManual-posting accounts only. Requires the post already be ready_to_copy.
DELETE/posts/:idRemoves the record. Does not un-post from the platform if already posted.

Schedules and configs

MethodPathNotes
GET/schedulesFilterable by account and date range; includes projected future runs.
PATCH/schedules/:idPause/resume, or change cadence.
GET / POST/configs
PATCH / DELETE/configs/:id
POST/configs/:id/generateTriggers GenerationService.generate on demand.

Topics and brand voice

MethodPathNotes
GET / POST/topicsShared across all accounts.
GET / POST/brand-profilesScoped to one account.

Competitors

MethodPathNotes
GET / POST/competitors
PATCH / DELETE/competitors/:idPause/resume tracking, or remove.

Inbox

MethodPathNotes
GET/dm-threadsScrapes live on every call. No background job.
PATCH/dm-threads/:idSets category (general / lead / community) and/or followUpAt.
GET/dm-threads/:id/messages
POST/dm-threads/:id/messagesSends a reply through the account's session.

Reply Manage

MethodPathNotes
GET/mentionsFilterable by status, including escalated.
POST/mentions/:id/approveSends the drafted reply. Works for a pending_approval mention or an escalated one that still has a draft ("send anyway").
POST/mentions/:id/reply-manuallySends a hand-typed reply, bypassing generation and every guardrail. The only path for a red-line escalation, which has no draft to approve.
POST/mentions/:id/dismiss
GET / POST/reply-configsCreate accepts confidenceThreshold and redlineTopics alongside requireApproval.
PATCH/reply-configs/:idToggle active, requireApproval, confidenceThreshold, or redlineTopics.

Knowledge base

MethodPathNotes
GET/knowledge-documentsLists documents with their chunk counts.
POST/knowledge-documentsCreates a document and indexes it into chunks immediately.
PATCH/knowledge-documents/:idEditing body re-indexes; editing only title/active doesn't.
DELETE/knowledge-documents/:idCascades to its chunks.

Billing and cost

MethodPathNotes
GET/billing/balance
POST/billing/topup
GET/cost/summaryTotal spend, broken down by kind.
GET/cost/eventsThe raw, itemized event ledger.

Health

MethodPathNotes
GET/healthNo guard. Liveness check.

Data model

The key Prisma tables and what each one owns.

On this page

AuthAccountsPosts and publishingSchedules and configsTopics and brand voiceCompetitorsInboxReply ManageKnowledge baseBilling and costHealth