CLI API (/cli/v1)

/cli/v1

tenantId?   — scope to specific tenant
all?        — boolean; return all assigned tenants (default: true for super_admin)

{
  timestamp: string;           // ISO 8601
  tenants: Array<{
    tenantId:         string;
    tenantName:       string;
    pendingApprovals: number;
    highRiskApprovals: number;
    runningAgents:    number;
    blockedActivities: number;
    costMtd:          number;  // month-to-date cost in USD
    creditUsed:       number;
    creditLimit:      number;
  }>;
  totals: {
    pendingApprovals:  number;
    runningAgents:     number;
    blockedActivities: number;
    costMtd:           number;
  };
  infrastructure: Array<{
    service:   string;   // 'api' | 'postgres' | 'mongo' | 'redis' | 'qdrant' | 'ollama'
    status:    'healthy' | 'degraded' | 'down';
    latencyMs: number | null;
    detail:    string | null;   // e.g. 'BullMQ: 12 active workers'
  }>;
}

tenantId?           — scope to tenant
status?             — pending | running | blocked | failed | all (default: pending+blocked)
type?               — blog_post | social_post | backlink | report | ...
agent?              — agent role slug
limit?              — default 50, max 200
cursor?             — pagination cursor

{
  pending: Array<QueueItem>;     // awaiting human approval
  running: Array<QueueItem>;     // agent currently executing
  blocked: Array<QueueItem>;     // blocked by dependency or error
  failed:  Array<QueueItem>;     // failed, needs intervention
  counts: {
    pending: number;
    running: number;
    blocked: number;
    failed:  number;
  };
  pagination: PaginationMeta;
}
 
interface QueueItem {
  activityId:   string;
  type:         string;
  title:        string;
  tenantId:     string;
  tenantName:   string;
  agentRole:    string | null;
  status:       string;
  riskLevel:    'low' | 'medium' | 'high' | null;
  ageMinutes:   number;          // how long in current status
  createdAt:    string;
}

{
  action:   'approve' | 'reject';
  ids?:     string[];                  // explicit list of approval IDs
  filter?: {                           // OR use a filter (not both)
    type?:      string;
    riskLevel?: 'low' | 'medium' | 'high';
    tenantId?:  string;
    ageMinutesGt?: number;             // older than N minutes
  };
  note?:    string;                    // optional note (appended to prompt on reject)
  dryRun?:  boolean;                   // preview without executing
}

{
  dryRun:    boolean;
  matched:   number;          // number of items matching the criteria
  resolved:  number;          // number successfully actioned (0 if dryRun)
  skipped:   number;          // already resolved or not accessible
  items: Array<{
    approvalId: string;
    title:      string;
    tenantName: string;
    result:     'resolved' | 'skipped' | 'error';
    error?:     string;
  }>;
}

Content-Type: text/event-stream

event: activity_meta
data: {"activityId":"01ARZ...","title":"Why Local SEO Matters","agentRole":"blog-writer","status":"running"}

event: text_delta
data: {"delta":"Local SEO is no longer optional..."}

event: text_delta
data: {"delta":" for businesses that rely on customers..."}

event: activity_completed
data: {"activityId":"01ARZ...","status":"awaiting_approval","wordCount":1240,"cost":0.018,"durationMs":220000}

file         — the file (required)
datasetSlug  — 'client-documents' | 'website-content' | 'competitor-research' (default: 'client-documents')
parseOnUpload — boolean, default true
parser       — 'builtin' | 'docling', default 'builtin'
tenantId     — required if not in X-Tenant-Id header

event: upload_started
data: {"fileName":"brand-brief.pdf","fileSize":1843200,"datasetId":"01ARZ..."}

event: upload_complete
data: {"ragFileId":"01BRZ...","status":"pending"}

event: ingestion_progress
data: {"ragFileId":"01BRZ...","stage":"parsing","progressPct":0}

event: ingestion_progress
data: {"ragFileId":"01BRZ...","stage":"embedding","progressPct":45,"chunksEmbedded":13,"chunksTotal":29}

event: ingestion_complete
data: {"ragFileId":"01BRZ...","chunksIndexed":29,"status":"indexed"}

event: ingestion_error
data: {"ragFileId":"01BRZ...","error":"File too large — max 10MB","stage":"upload"}

{
  query:     string;         // the natural language input
  context: {
    tenantId?:  string;      // current session context
    surface:    'cli';
    history?:   string[];    // last N commands for context
  };
}

{
  type: 'data' | 'action' | 'clarification';
 
  // type: 'data' — information response
  data?: {
    text:    string;          // plain text for terminal output
    table?:  TableData;       // structured table the CLI renders
  };
 
  // type: 'action' — proposed command to execute
  action?: {
    command:      string;     // the slash command to run e.g. '/bulk-approve ...'
    description:  string;     // human-readable description of what will happen
    destructive:  boolean;    // whether this changes state
    preview?:     TableData;  // what will be affected (for destructive ops)
  };
 
  // type: 'clarification' — need more info
  clarification?: {
    question: string;
    options?: string[];       // suggested answers
  };
}

POST /admin/v1/api-keys          — create key for a user
GET  /admin/v1/api-keys          — list keys
DELETE /admin/v1/api-keys/:id    — revoke key