Brand analysis and audits
The services behind Brand Analysis: the one-line audit and its stages,
the diagnosis, material attached to a new-site audit, content research,
market research, Google Search Console, and fixes proposed to the customer’s
own website repository. Package pulse.v1; the least role of each method is
in its table. See Audit a domain.
Notes
- One deadline.
GenerateDiagnosticand a score-onlyRunAuditrun under one end-to-end budget,PULSE_AUDIT_DEADLINE_SECONDS(170 seconds by default). Each phase gets a budget from what is left; a phase that does not finish is named on the result as not completed within the budget, and the diagnosis is returned as a partial result rather than discarded. - Judged output.
Diagnostic.channel_prescriptionsandbrand_visibilityhold only proposals the judging ladder kept;judgementslists every verdict. - Audit runs.
RunAuditruns the stages detached from the call (bounded at 45 minutes), resumes from the first stage not done, reuses a run from the last 24 hours unlessforceis set, and attaches to a run already in flight.score_onlyruns justnormalizeandscoreon the URL as given; an identical score-only run withinPULSE_AUDIT_CACHE_TTL(one hour by default) is reused unlessforce. Read the report withGetAuditRun(AuditRun.score_report). - Stages.
stageis a stable identifier: show it as-is or map it to your own labels, but do not rely on the set of stages or their order. A stage that could not run because an earlier one did not finish isskipped, with anerrorthat startsblocked:.queue_positionis set while a stage waits for model capacity. The terminal event has an emptystageand the run’s finalrun_status. WithTIDE_HEALTH_URLset, each stage reports to agent health aspulse-audit-<stage>. - Stored reads. The market research
List*methods (ListDiscoveredChannels,ListTrendingPosts) read what earlier research and audits persisted; they search nothing and spend no model time. Guest spots that research finds are saved as partners (Leads → Partners), scored by topical relevance, never by an audience figure. The service keeps its older proto name. - Changing a site.
ApplyAuditActionsmodes other thanplanneedPULSE_APPLY_ENABLED=true,PULSE_AUDIT_APPLY=trueand an admin; every mode needsrepo_pathinsidePULSE_APPLY_ROOT.SiteRepoService.ProposeSiteFixneeds the same two switches and an admin, writes only to a newpulse/<run>-<finding>branch and opens a pull request.ConnectSiteRepoandDisconnectSiteRepoalso check for an admin, although their table role is editor. See Website repository. - Search Console.
StartSearchConsoleConnectreturns Google’s consent address; Google returns to/oauth/search-console/callback. Without the Google OAuth client or an httpsPULSE_PUBLIC_BASE_URLthe answer says what is not set up. See Google.
DiagnosticService
Multichannel business diagnostic — positioning, SWOT, competitor analysis.
pulse.v1.DiagnosticService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
CreateDiagnostic | CreateDiagnosticRequest → Diagnostic | editor | CreateDiagnostic creates a new diagnostic record from user-provided business info. |
GetDiagnostic | GetDiagnosticRequest → Diagnostic | viewer | GetDiagnostic fetches a single diagnostic by ID. |
ListDiagnostics | ListDiagnosticsRequest → ListDiagnosticsResponse | viewer | ListDiagnostics returns paginated diagnostics for the current user/org. |
GenerateDiagnostic | GenerateDiagnosticRequest → stream StreamChunk | editor | GenerateDiagnostic streams AI-generated diagnostic analysis in real-time. |
UpdateDiagnostic | UpdateDiagnosticRequest → Diagnostic | editor | UpdateDiagnostic updates a diagnostic’s metadata or user notes. |
ExportDiagnosticPDF | ExportDiagnosticPDFRequest → ExportDiagnosticPDFResponse | viewer | ExportDiagnosticPDF generates a branded PDF export of the diagnostic. |
ApplyAuditActions | ApplyAuditActionsRequest → ApplyAuditActionsResponse | editor | AuditURL was removed: a site score is AuditPipelineService.RunAudit with score_only set, and the report is AuditRun.score_report. ApplyAuditActions audits a URL and maps the auto-applyable fix-artifacts into a server-local repository (stack-aware, idempotent). mode escalates from “plan” (dry-run, default, no side effects) to “apply”/“commit”/“pr”. Copy/infra actions are returned as manual for human review, never applied. |
Also uses StreamChunk, PaginationRequest, PaginationResponse, AssistantToolEvent, AssistantProposal, Channel.
// ContentSuggestion is one concrete content idea within a ChannelPrescription.
message ContentSuggestion {
string title = 1;
string description = 2;
string cta = 3;
}
// ChannelPrescription is the AI's structured recommendation for a single
// channel — role in the overall strategy, priority, concrete content ideas,
// preferred CTA style, and the KPIs that matter for it.
message ChannelPrescription {
Channel channel = 1;
string role = 2;
string priority = 3;
repeated ContentSuggestion suggestions = 4;
string cta_recommendation = 5;
repeated string kpis = 6;
// The judging ladder's verdict on this prescription (cmd/judgement_gate.go).
// Only concur and unable-to-judge ever appear here: a dissented
// prescription is withheld and lives only in Diagnostic.judgements.
// Unset = judging was off (PULSE_JUDGEMENT=off) or it predates the gate.
runink.ui.judgement.v1.Judgement judgement = 7;
}
// DocumentPrescription is the AI's structured recommendation for a single
// document format — its role, priority, and concrete ideas.
message DocumentPrescription {
string format = 1;
string role = 2;
string priority = 3;
repeated ContentSuggestion suggestions = 4;
}
// BrandVisibilityInsight is a Generative-Engine-Optimization finding: how to
// shape the brand's lexical/semantic presence so generative-AI metasearch
// engines (AI Overviews, Perplexity, ChatGPT, etc.) recognise, surface, and
// cite the company in context — a distinct insight stream from the
// audience-targeting prescriptions above.
message BrandVisibilityInsight {
// entity_authority | semantic_topics | answer_framing | lexical_relevance |
// structured_data | authority_sources
string dimension = 1;
string insight = 2; // what the diagnosis found about current AI-search visibility
repeated string target_terms = 3; // entities/phrases/queries to own for AI-search lexical relevance
repeated string actions = 4; // concrete actions to raise generative-AI discoverability
string rationale = 5; // why this shapes brand awareness in AI/metasearch engines
// The judging ladder's verdict on this insight; see ChannelPrescription.judgement.
runink.ui.judgement.v1.Judgement judgement = 6;
}
// AudienceSegment is one tier of a 360-degree audience map (e.g. decision
// makers, influencers, end users), with the areas/roles/technologies that
// define it.
message AudienceSegment {
string level = 1;
repeated string areas = 2;
repeated string roles = 3;
repeated string technologies = 4;
}
// CronogramTask is one task in the multichannel execution calendar.
message CronogramTask {
int32 week = 1;
Channel channel = 2;
string task = 3;
bool completed = 4;
}
// Diagnostic is a full multichannel business diagnostic report.
message Diagnostic {
string id = 1;
string user_id = 2;
string business_name = 3;
string industry = 4;
string niche = 5;
string target_audience = 6;
string current_channels = 7; // comma-separated active channels
string competitors = 8; // comma-separated competitor names
string business_description = 9; // user's free-form business description
string website_url = 10;
string positioning_analysis = 11;
string swot_analysis = 12;
string channel_recommendations = 13;
string content_strategy = 14;
string competitive_landscape = 15;
string ai_opinion = 16; // strategic opinion from the AI market-analyst
string status = 17; // "pending", "generating", "completed", "error"
map<string, string> metadata = 18;
google.protobuf.Timestamp created_at = 19;
google.protobuf.Timestamp updated_at = 20;
// Structured breakdown of channel_recommendations/content_strategy above,
// parsed via a schema-constrained LLM call (see GenerateStructured in
// cmd/model_server.go) instead of left as free text for the client to
// guess at. Populated by GenerateDiagnostic; empty on a freshly-created,
// not-yet-generated Diagnostic.
repeated ChannelPrescription channel_prescriptions = 21;
repeated AudienceSegment audience_segments = 22;
repeated CronogramTask cronogram = 23;
// URLs/titles of the real sources (site, LinkedIn, web search results)
// the AI actually grounded this diagnostic in — see internal/metasearch.
repeated string sources_used = 24;
// Real, backend-verified actions taken during generation (e.g. "Scraped
// live content from acme.com"), same convention as StreamChunk.agent_tasks
// — streamed live during GenerateDiagnostic and persisted here so the
// trace survives after generation finishes, not just visible mid-stream.
repeated string agent_tasks = 25;
// User's selected goals for the diagnostic
repeated string goals = 26;
repeated DocumentPrescription document_prescriptions = 27;
// Generative-Engine-Optimization insights — how to shape brand awareness /
// discoverability in AI metasearch engines via lexical relevance, split out
// from the audience-targeting prescriptions above.
repeated BrandVisibilityInsight brand_visibility = 28;
// Every verdict the judging ladder reached on this diagnostic's proposals
// (channel prescriptions + brand-visibility insights), accepted AND
// rejected, with the ladder's own counts. A dissented proposal appears
// ONLY here (accepted=false), never in the lists above. Kept in PULSE's own
// store with the structured analysis. Unset = not judged.
runink.ui.judgement.v1.JudgementSet judgements = 29;
}
message CreateDiagnosticRequest {
string business_name = 1;
string industry = 2;
string niche = 3;
string target_audience = 4;
string current_channels = 5;
string competitors = 6;
string business_description = 7;
string website_url = 8;
repeated string goals = 9;
}
message GetDiagnosticRequest {
string id = 1;
}
message ListDiagnosticsRequest {
PaginationRequest pagination = 1;
}
message ListDiagnosticsResponse {
repeated Diagnostic diagnostics = 1;
PaginationResponse pagination = 2;
}
message GenerateDiagnosticRequest {
string diagnostic_id = 1; // ID of the pre-created diagnostic to populate
}
message UpdateDiagnosticRequest {
string id = 1;
string business_name = 2;
string industry = 3;
string niche = 4;
string target_audience = 5;
string current_channels = 6;
string competitors = 7;
string business_description = 8;
string website_url = 9;
map<string, string> metadata = 10;
}
message ExportDiagnosticPDFRequest {
string diagnostic_id = 1;
}
message ExportDiagnosticPDFResponse {
bytes pdf_data = 1;
string filename = 2;
// The same PDF at a signed, expiring /media URL (the media vault), for a
// native app: Android cannot save bytes where the person can open them, so
// it hands this to the system browser, which downloads it. Empty when the
// media vault is unavailable; the bytes are always set.
string download_url = 3;
}
// ApplyAuditActionsRequest audits url and applies auto-fixable actions to the
// repo at repo_path. mode ∈ {plan,apply,commit,pr}; empty = plan (dry-run).
message ApplyAuditActionsRequest {
string url = 1;
string repo_path = 2;
string profile = 3;
string mode = 4; // plan|apply|commit|pr
string branch = 5; // default: seo/pulse-remediation
string base = 6; // default: main
}
// ApplyAuditActionsResponse reports the detected stack, the planned/applied file
// changes, the manual (copy/infra) actions left for review, and the git result.
message ApplyAuditActionsResponse {
string stack = 1;
double overall_score = 2;
repeated PlannedChange changes = 3;
repeated AuditAction manual = 4;
ApplyGitResult git = 5;
string pr_body = 6;
}
// PlannedChange is one file the agent would create/modify/skip.
message PlannedChange {
string path = 1;
string op = 2; // create|modify|skip
string check_id = 3;
string reason = 4;
}
// ApplyGitResult reports how far the git/PR step got, with manual instructions
// when credentials or gh are unavailable.
message ApplyGitResult {
string branch = 1;
bool committed = 2;
bool pushed = 3;
string pr_url = 4;
string instructions = 5;
}
// AuditAction is a concrete remediation fix-artifact for a check: the actual
// content to apply (robots.txt, canonical tag, JSON-LD block, rewritten title,
// header config) plus where it goes and whether it's safe to auto-apply.
message AuditAction {
string check_id = 1;
string title = 2;
string rationale = 3;
string severity = 4; // critical|high|medium|low
string type = 5; // file_create|head_insert|content_edit|header_config|manual
string target_hint = 6;
string artifact = 7; // the concrete content/snippet to apply
string confidence = 8; // high|medium|low
bool auto_apply = 9;
double impact = 10;
}AuditPipelineService
The one-phrase audit pipeline (“Audit example.com”): the user types a domain and every PULSE page is populated by inference — crawl, site score, trend slice, the diagnosis, the deterministic fan-out (campaign, approval drafts, follow-up cycle, schedule, creatives, course, persona, radar summary), then radar research and leads. Every stage is tracked (audit_runs / audit_stages), owner scoped, and reported honestly: a stage is done only when it wrote at least one row or recorded “0 found” from a source that actually answered. A run whose required stage failed ends partial or failed, never completed.
pulse.v1.AuditPipelineService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
RunAudit | RunAuditRequest → stream AuditProgress | editor | RunAudit starts (or attaches to, or resumes) the caller’s audit of a domain and streams stage progress until the run ends. A second call for the same (caller, domain) while a run is active attaches to it; a call after a failed/partial run resumes from the first stage that is not done; a call within 24h of a completed run returns that run unless force is set. A score_only call is its own run: it never attaches to or replays a full audit (nor a full audit to it); see RunAuditRequest.score_only. |
GetAuditRun | GetAuditRunRequest → AuditRun | viewer | |
ListAuditRuns | ListAuditRunsRequest → ListAuditRunsResponse | viewer | |
GetAuditAiVisibility | GetAuditAiVisibilityRequest → AuditAiVisibility | viewer | GetAuditAiVisibility returns what a run’s genai_visibility stage measured, finding by finding, with the evidence for each. |
GetAuditFindings | GetAuditFindingsRequest → AuditFindings | viewer | GetAuditFindings returns what a run found for the business: leads with their contacts, possible competitors, where it wins and loses against each, niches worth exploring and partners with their contacts. Each kind says whether it was found, found nothing, or was not measured. |
DeleteAuditRuns | DeleteAuditRunsRequest → DeleteAuditRunsResponse | editor | DeleteAuditRuns deletes some of the caller’s full audit runs, or every run of one domain but the newest (all_but_latest, with the domain typed back as confirm). Removed: each run, its stages, its findings, its AI-visibility rows and its content-gaps snapshot unless a campaign plan uses it. Kept: leads, campaigns, drafts, the diagnosis and the site-score history. A run still in flight is refused, never deleted. |
GetAuditAudience | GetAuditAudienceRequest → AuditAudience | viewer | GetAuditAudience returns who a run found the business sells to and what it sells (the research inputs it saved), each with where it came from. |
Also uses AuditAction.
// AuditReport is the full audit result: the output contract of the scoring
// engine. overall_score is the weighted mean of composites; benchmark_mode is
// "relative" or "absolute"; skipped_data_sources lists adapters the user could
// configure to raise coverage.
message AuditReport {
string url = 1;
google.protobuf.Timestamp audited_at = 2;
double overall_score = 3;
repeated AuditComposite composites = 4;
repeated string skipped_data_sources = 5;
string benchmark_mode = 6;
repeated AuditRecommendation recommendations = 7;
repeated AuditAction actions = 8;
}
// AuditComposite is one of the four scored dimensions. coverage is the fraction
// (0-1) of the composite's weight that was actually scored — a 90 at 0.4
// coverage is very different from a 90 at 1.0.
message AuditComposite {
string id = 1;
string label = 2;
double score = 3;
double weight = 4; // normalized 0-1
double coverage = 5; // 0-1
repeated AuditSignal signals = 6;
}
// AuditSignal is a scored signal within a composite.
message AuditSignal {
string id = 1;
double score = 2;
double weight = 3; // normalized 0-1 within its composite
double coverage = 4; // 0-1
repeated AuditCheck checks = 5;
}
// AuditCheck is a single check's outcome. status is "scored" | "skipped" |
// "error"; mode is "relative" | "absolute" for benchmark checks (else empty).
message AuditCheck {
string id = 1;
double score = 2;
string status = 3;
string raw_value = 4;
string notes = 5;
string mode = 6;
}
// AuditRecommendation is a lowest-scoring check surfaced by global weighted
// impact (check_weight × signal_weight × composite_weight), so the biggest
// wins bubble up.
message AuditRecommendation {
string check_id = 1;
double score = 2;
double impact = 3;
string notes = 4;
}
message RunAuditRequest {
string domain = 1; // "example.com", "https://example.com/…" — normalised server-side
bool force = 2; // start a fresh run even when a completed one is < 24h old
// What the person told the audit about the business. Any field set starts a
// fresh run built on it; a niche, industry or business name lets the
// research stages start without waiting for the model to infer one.
AuditTuning tuning = 3;
// score_only runs only normalize + score, on the URL exactly as given, as a
// tracked run of its own (not listed by ListAuditRuns). It attaches only to
// an identical score_only run in flight and is never replayed from a stored
// run. A score computed by an earlier score_only call with the same inputs
// within PULSE_AUDIT_CACHE_TTL is reused unless force is set.
bool score_only = 4;
// Weighting profile (e.g. "ai-focused"), empty = default. score_only only.
string scoring_profile = 5;
// 2-3 competitor URLs switch the benchmark-dependent checks to relative
// mode. score_only only.
repeated string competitor_urls = 6;
}
// The new-audit form's details. Every field is optional.
message AuditTuning {
string business_name = 1;
string industry = 2;
string niche = 3;
string target_audience = 4;
string competitors = 5; // free text: names or URLs, comma separated
string business_description = 6; // "What do you sell?" plus any extra context
repeated string goals = 7;
string linkedin_url = 8;
string instagram_handle = 9;
// Material uploaded through AuditAttachmentService (photos, a short video,
// product documents, voice notes) the audit compares the brand against.
// Owner scoped: an id that is not the caller's is refused.
repeated string attachment_ids = 10;
// "Where are most of your customers?" — asked only when the site did not
// state it; used as the region only when no check on the site measures one.
string customer_region = 11;
}
// AuditProvenance says where a stage's output came from: "sourced" (read from
// the web), "inferred" (the model's reasoning over sourced input), or "mixed".
message AuditProvenance {
string kind = 1; // sourced | inferred | mixed | none
repeated string source_urls = 2; // bounded; the pages the stage actually read
string basis = 3; // one line: what the inference rests on
}
// AuditProgress is one event of a run. A stage event has stage set; the run's
// terminal event has stage == "" and run_status set to its final value.
message AuditProgress {
string run_id = 1;
string stage = 2; // normalize, crawl, score, trends, diagnosis, fanout_*, niche, radar_*, leads
string status = 3; // pending | running | done | failed | skipped
string detail = 4;
map<string, int32> counts = 5;
string error = 6; // set whenever status is failed (and on a failed/partial terminal event)
AuditProvenance provenance_summary = 7;
int32 queue_position = 8; // >0 while this stage waits for the model lane
string run_status = 9; // running | completed | partial | failed
string domain = 10;
string diagnostic_id = 11;
bool attached = 12; // this stream joined a run another call started
int32 attempt = 13;
}
message AuditStage {
string stage = 1;
string status = 2;
int32 attempt = 3;
map<string, int32> counts = 4;
string error = 5;
string detail = 6;
google.protobuf.Timestamp started_at = 7;
google.protobuf.Timestamp finished_at = 8;
// Not applicable to this run (an optional stage skipped for a reason that
// is not a failure, e.g. no material was attached): neither finished nor
// unfinished, and not counted in "N of M parts".
bool not_applicable = 9;
}
message AuditRun {
string id = 1;
string domain = 2;
string diagnostic_id = 3;
string status = 4; // running | completed | partial | failed
google.protobuf.Timestamp created_at = 5;
google.protobuf.Timestamp finished_at = 6;
repeated AuditStage stages = 7;
// The site score the run's score stage saved; unset when it saved none.
AuditReport score_report = 8;
bool score_only = 9;
}
message GetAuditRunRequest {
string run_id = 1;
}
message ListAuditRunsRequest {
int32 limit = 1; // default 20, max 100
string domain = 2; // optional filter
}
message ListAuditRunsResponse {
repeated AuditRun runs = 1;
}
message GetAuditAiVisibilityRequest {
string run_id = 1;
}
// One AI-access requirement read from the site itself.
message AiAccessCheck {
string kind = 1; // crawler | llms_txt | server_rendered | structured_data
string item = 2; // the crawler's name, or the file / page checked
string state = 3; // pass | fail | not_measured
string evidence = 4; // the line that decided it
string evidence_url = 5;
// The site-score check whose fix-artifact (in the score report's actions,
// applied through ApplyAuditActions) fixes a failure; "" when none does.
string fix_check_id = 6;
}
// One buyer question read on a search engine's own result page.
message AiAnswerCheck {
string question = 1;
string basis = 2; // what the question was derived from
string engine = 3; // the engine whose page was read
string serp_url = 4; // that page
// cited | not_cited | no_ai_answer | not_measured. not_measured is never
// counted as not cited.
string state = 5;
string why = 6; // set when not_measured
repeated string sources = 7; // the AI answer's cited links
repeated string competitors_cited = 8; // cited hosts matching a named competitor
repeated string other_cited = 9; // every other cited host
int32 organic_rank = 10; // the brand's position among organic results; 0 = not among them
int32 organic_count = 11; // organic results on the page as loaded; 0 = page not read
}
message AuditAiVisibility {
string run_id = 1;
string domain = 2;
bool measured = 3; // false: the stage stored nothing (absent, not empty)
repeated AiAccessCheck access = 4;
repeated AiAnswerCheck answers = 5;
string engines_covered = 6; // e.g. "DuckDuckGo"
string not_covered = 7; // what this measurement does not read
}
message GetAuditFindingsRequest {
string run_id = 1; // "" = the caller's latest full audit
}
// FindingContact is what a page publishes about how to reach someone.
message FindingContact {
string email = 1;
string phone = 2;
string website = 3;
string linkedin = 4;
}
message AuditFinding {
string kind = 1; // lead | competitor | advantage | niche | partner
string title = 2; // the company, competitor, niche or partner
string detail = 3; // why, in plain words
string source_url = 4; // where it was found or measured
string basis = 5; // measured | named (by the owner) | judged (model proposal the plan gate kept)
FindingContact contact = 6;
repeated string wins = 7; // advantage: checks this business meets and the competitor does not
repeated string losses = 8; // advantage: checks the competitor meets and this business does not
string lead_id = 9; // lead: its row on the Leads page
string judgement = 10; // judged: the plan gate's verdict
bool measured = 11; // false = this item could not be measured (detail says why)
string id = 12; // the finding's own id (a partner's automation target id)
}
// AuditFindingKind is one kind's state for the run.
message AuditFindingKind {
string kind = 1;
string state = 2; // found | none_found | not_measured
string why = 3; // none_found / not_measured: the stage's own reason
string stage = 4; // the stage that produced it
}
message AuditFindings {
string run_id = 1;
string domain = 2;
repeated AuditFinding findings = 3;
repeated AuditFindingKind kinds = 4;
}
message DeleteAuditRunsRequest {
repeated string run_ids = 1; // the caller's runs to delete
// Delete every run of domain except its newest; confirm must equal the
// domain as ListAuditRuns returns it (the typed confirmation).
bool all_but_latest = 2;
string domain = 3;
string confirm = 4;
// With all_but_latest: delete the newest run too.
bool include_latest = 5;
// START OVER (Settings › Account, Brand Analysis history): every run of the
// caller (this account or agency client only) AND what the runs produced —
// stages, findings, AI-visibility rows, site scores, insight snapshots
// (content gaps, scenarios), every diagnosis, follow-up cycles with their
// tasks and check-ins, market research (summaries, channels, trending posts,
// imported partners), campaign proposals never accepted with their
// campaigns, drafts never approved with their scheduled rows, creative
// briefs and course outlines the audits made, and the leads they found.
// confirm must equal domain, a domain the caller audited. Refused while any
// of the caller's audits is running. Never deleted: anything published,
// measured results (post_results), integrations, leads added by hand,
// imported or won.
bool start_over = 6;
// Start over also deletes accepted campaigns (with their plans and roadmap).
bool also_accepted_campaigns = 7;
// No longer read: start over always deletes the leads audits found
// (source "scraped" or linked from a finding) unless won (owner, 2026-10-30).
bool also_audit_leads = 8;
// Start over also deletes approved or scheduled items not sent yet.
bool also_approved_unsent = 9;
// Count what would go, delete nothing (the dialog's preview).
bool dry_run = 10;
}
// What DeleteAuditRuns removed, row by row.
message DeleteAuditRunsResponse {
repeated string deleted_run_ids = 1;
int32 stages = 2;
int32 findings = 3;
int32 ai_visibility = 4;
int32 snapshots = 5;
// Runs still in flight: never deleted.
repeated string refused_run_ids = 6;
// Start over only (0 for a plain delete).
int32 campaign_plans = 7;
int32 campaigns = 8;
int32 drafts = 9; // content rows never approved
int32 approved_unsent = 10; // approved or scheduled, not sent (only when asked)
int32 scheduled_posts = 11; // pending scheduled posts removed with them
int32 leads = 12; // only when asked
int32 roadmap_items = 13;
int32 planner_tasks = 14;
int32 diagnostics = 15;
int32 competitor_channels = 16;
// Published items kept (never deleted), for the dialog's summary.
int32 kept_published = 17;
bool dry_run = 18;
// Start over refused: an audit is running (its run id).
string refused_running = 19;
int32 trending_posts = 20; // trending posts the research saved for the runs' niches
// Start over (owner, 2026-10-30: "clear everything the audits produced").
int32 cycles = 21; // follow-up cycles the audits made, with their tasks
int32 check_ins = 22; // the weekly check-ins of those cycles
int32 creatives = 23; // creative briefs the audits made
int32 courses = 24; // course outlines the audits made
int32 market_summaries = 25; // radar summaries
int32 partners = 26; // partners imported from the research (hand-added ones stay)
int32 site_scores = 27; // site scores the runs saved
// What stays, for the dialog: leads added by hand, imported or won;
// accepted campaigns (only when the person keeps them); connected accounts.
int32 kept_leads = 28;
int32 kept_campaigns = 29;
int32 kept_integrations = 30;
}
message GetAuditAudienceRequest {
string run_id = 1;
}
// One group of people the business sells to, as the run found them.
message AudiencePersona {
string name = 1;
string source = 2; // tuning | owner | leads | audience
string evidence = 3; // the line it was drawn from ("" when none was kept)
}
// One thing the business sells, in the site's own words when read there.
message AudienceOffering {
string name = 1;
string quote = 2; // the site's words ("" when the owner typed it)
string source = 3; // site | tuning
string source_url = 4; // the page read ("" for the owner's own words)
}
message AuditAudience {
string run_id = 1;
string domain = 2;
// false: the run saved no audience (absent, not empty).
bool measured = 3;
repeated AudiencePersona personas = 4;
repeated AudienceOffering offerings = 5;
repeated string problems = 6; // the problems the research found for them
}AuditAttachmentService
The material a person gives the new-site audit besides text: photos or a short video of the store or product, product documents (PDF, DOCX, TXT, MD) and voice notes. PULSE audits the brand AGAINST that material: does the site say what the documents and photos show, what is inconsistent, which benefits are not communicated.
UPLOAD IS CHUNKED OVER UNARY RPCS (Begin → Chunk… → Finish) because the web client speaks gRPC-Web, which has no client streaming. Every call is owner scoped: an upload or attachment of another user is NOT_FOUND. Bytes are sealed in PULSE’s appfs root the moment Finish accepts them; nothing is ever written to disk in plaintext. Pass the returned ids in AuditTuning.attachment_ids; an attachment used by a run lives as long as that run, one never used expires (expires_at).
pulse.v1.AuditAttachmentService, declared in attachments.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
GetAttachmentLimits | GetAttachmentLimitsRequest → AttachmentLimits | viewer | What this instance accepts and can understand. Read it before showing the pickers: an instance without a vision tier still accepts photos but says up front that it cannot look at them. |
BeginAttachmentUpload | BeginAttachmentUploadRequest → BeginAttachmentUploadResponse | editor | Declares a file. Refused (INVALID_ARGUMENT, with a sentence the UI can show) when its type is not accepted or its declared size is over the cap. |
UploadAttachmentChunk | UploadAttachmentChunkRequest → UploadAttachmentChunkResponse | editor | Appends one chunk at offset (must equal the bytes received so far; a retried chunk at an already-received offset is acknowledged, not duplicated). At most max_chunk_bytes per call. |
FinishAttachmentUpload | FinishAttachmentUploadRequest → AuditAttachment | editor | Checks the received bytes (size, sha256 when given, real file type, pages/duration caps), seals them and returns the attachment. Extraction then runs in the background: poll GetAttachment until status is not PROCESSING. Documents are usually READY on return. |
GetAttachment | GetAttachmentRequest → AuditAttachment | viewer | |
ListAttachments | ListAttachmentsRequest → ListAttachmentsResponse | viewer | |
DeleteAttachment | DeleteAttachmentRequest → DeleteAttachmentResponse | editor | Removes the sealed bytes and the extracted text. Idempotent. |
enum AttachmentKind {
ATTACHMENT_KIND_UNSPECIFIED = 0;
ATTACHMENT_KIND_IMAGE = 1; // jpeg, png, webp
ATTACHMENT_KIND_VIDEO = 2; // mp4, webm (short)
ATTACHMENT_KIND_DOCUMENT = 3; // pdf, docx, txt, md
ATTACHMENT_KIND_AUDIO = 4; // a voice note: wav, webm/ogg opus, m4a, mp3
}
enum AttachmentStatus {
ATTACHMENT_STATUS_UNSPECIFIED = 0;
ATTACHMENT_STATUS_PROCESSING = 1; // sealed; extraction still running
ATTACHMENT_STATUS_READY = 2; // done; see analysis for what was obtained
ATTACHMENT_STATUS_FAILED = 3; // stored, but nothing could be read (see detail)
}
// What PULSE could actually get out of the file. Three of these are honest
// "could not" states, never a guess: an image with no vision tier is
// IMAGE_UNDERSTANDING_UNAVAILABLE, not a text model's description of a
// filename.
enum AttachmentAnalysis {
ATTACHMENT_ANALYSIS_UNSPECIFIED = 0;
ATTACHMENT_ANALYSIS_PENDING = 1;
ATTACHMENT_ANALYSIS_TEXT_EXTRACTED = 2; // document text read
ATTACHMENT_ANALYSIS_NO_TEXT_FOUND = 3; // read fine, but no text in it (e.g. a scanned PDF)
ATTACHMENT_ANALYSIS_IMAGE_DESCRIBED = 4; // the vision tier described it (video: its frames)
ATTACHMENT_ANALYSIS_IMAGE_UNDERSTANDING_UNAVAILABLE = 5; // no vision tier on this instance, or it did not answer
ATTACHMENT_ANALYSIS_FRAMES_NOT_ANALYSED = 6; // video stored; frames could not be sampled
ATTACHMENT_ANALYSIS_TRANSCRIBED = 7; // voice note transcribed (Voxtral)
ATTACHMENT_ANALYSIS_TRANSCRIPTION_UNAVAILABLE = 8; // no voice tier, or it did not answer
ATTACHMENT_ANALYSIS_FAILED = 9; // the file could not be parsed
}
message GetAttachmentLimitsRequest {}
message AttachmentTypeLimit {
AttachmentKind kind = 1;
repeated string content_types = 2; // accepted MIME types
repeated string extensions = 3; // accepted extensions, lower case, no dot
int64 max_bytes = 4;
int32 max_duration_seconds = 5; // video/audio; 0 = not applicable
int32 max_pages = 6; // documents; 0 = not applicable
}
message AttachmentLimits {
repeated AttachmentTypeLimit types = 1;
int32 max_attachments_per_audit = 2;
int32 max_chunk_bytes = 3;
// Whether the instance can look inside the material, decided from its
// configuration (a vision tier, a voice tier, a frame sampler). False is
// shown to the person before they upload.
bool image_understanding_available = 4;
bool transcription_available = 5;
bool video_frames_available = 6;
int32 unused_retention_hours = 7; // an attachment no run used is removed after this
}
message BeginAttachmentUploadRequest {
string filename = 1; // shown back and cited in findings; path parts are dropped
string content_type = 2; // as the picker reports it; the bytes are checked at Finish
int64 size_bytes = 3; // declared total size; Finish refuses a different count
}
message BeginAttachmentUploadResponse {
string upload_id = 1;
AttachmentKind kind = 2;
int32 max_chunk_bytes = 3;
google.protobuf.Timestamp expires_at = 4; // an unfinished upload is dropped after this
}
message UploadAttachmentChunkRequest {
string upload_id = 1;
int64 offset = 2;
bytes data = 3;
}
message UploadAttachmentChunkResponse {
int64 received_bytes = 1;
}
message FinishAttachmentUploadRequest {
string upload_id = 1;
string sha256_hex = 2; // optional; checked when set
}
message AuditAttachment {
string id = 1;
string filename = 2;
string content_type = 3; // as detected from the bytes
AttachmentKind kind = 4;
int64 size_bytes = 5;
AttachmentStatus status = 6;
AttachmentAnalysis analysis = 7;
string detail = 8; // one sentence for the person: what was read, or why not
string summary = 9; // first part of what was extracted/described (bounded)
int32 extracted_chars = 10; // size of the full extracted text the audit can use
int32 page_count = 11; // documents; 0 = unknown
int32 duration_seconds = 12; // video/audio; 0 = unknown
int32 frames_analysed = 13; // video
string audit_run_id = 14; // the run that used it; "" = not used yet
google.protobuf.Timestamp created_at = 15;
google.protobuf.Timestamp expires_at = 16; // unset once a run uses it
// What the audit run (audit_run_id) found comparing the site with this
// material, each judged by the plan gate. Empty until that run's diagnosis.
repeated AttachmentFinding findings = 17;
}
// One brand-vs-material finding drawn from an attachment.
message AttachmentFinding {
string type = 1; // gap | inconsistency | uncommunicated_benefit | confirmed
string finding = 2; // one sentence
string action = 3; // what to change on the site or in marketing
string judgement = 4; // the plan gate's verdict text; "" = not judged (PULSE_JUDGEMENT=off)
}
message GetAttachmentRequest {
string attachment_id = 1;
}
message ListAttachmentsRequest {
string audit_run_id = 1; // optional: only those a run used
}
message ListAttachmentsResponse {
repeated AuditAttachment attachments = 1;
}
message DeleteAttachmentRequest {
string attachment_id = 1;
}
message DeleteAttachmentResponse {
bool deleted = 1; // false when there was nothing to delete
}SitePreviewService
What the new-audit wizard can show the person before they type anything: the site’s own name and description, and the social profiles it links to. One page read, no model call, no write. Everything returned is what the page itself says, so the wizard can ask “is this right?” instead of showing empty fields.
pulse.v1.SitePreviewService, declared in site_preview.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
PreviewSite | PreviewSiteRequest → SitePreview | viewer |
message PreviewSiteRequest {
string url = 1; // "bakery.com" or a full URL; normalised server-side
}
// A social profile the page links to.
message SiteProfile {
string network = 1; // instagram | facebook | linkedin | tiktok | youtube | x | pinterest
string url = 2;
string handle = 3; // "@name" when the link names one; "" otherwise
}
message SitePreview {
string url = 1; // the page that was read
// False: the page could not be read (why says so). Not an empty site.
bool read = 2;
string why = 3;
string name = 4; // og:site_name, else <title>; "" when the page has neither
string description = 5; // meta description, else og:description; "" when absent
repeated SiteProfile profiles = 6;
// Where the business's customers are, as the page itself states it
// (cmd/region.go); "" = not measured. region_source names the check.
string region = 7;
string region_source = 8;
}ContentResearchService
ContentResearchService — the audit’s deep content research (release 5). From what an audit MEASURED (the site’s own text and what it sells, the niche, trending posts, competitor channels, trend searches, leads and the people the business sells to), PULSE fans out scenarios: one person × one problem they have × one angle × the channel formats it suits, each with 3-5 post ideas, the findings that back it and a research pass through PULSE’s own crawler. Every scenario is one content-skill run on PULSE’s own inference (OpenBias, Go checks, plan gate); a withheld one is listed with the reason. Nothing here publishes.
pulse.v1.ContentResearchService, declared in content_scenarios.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
ListContentScenarios | ListContentScenariosRequest → ListContentScenariosResponse | viewer | ListContentScenarios returns the scenarios of a run ("" = the caller’s latest run that has them), best first, withheld ones last. No model call. |
GetResearchTuning | GetResearchTuningRequest → ResearchTuning | viewer | GetResearchTuning returns what the caller saved, and what the latest audit found to seed it with (people it sells to, what it sells). |
SaveResearchTuning | SaveResearchTuningRequest → ResearchTuning | editor | SaveResearchTuning stores the caller’s tuning (per account; an agency client is its own account). The next audit and every re-tune use it. |
RetuneContentScenarios | RetuneContentScenariosRequest → RetuneContentScenariosResponse | editor | RetuneContentScenarios re-runs the scenarios of a finished run with the saved tuning, detached; ListContentScenarios shows the result. |
// One post idea of a scenario.
message ScenarioItem {
string hook = 1; // the first line people see
string format = 2; // instagram_feed | instagram_carousel | instagram_reel | instagram_story | youtube_long | youtube_shorts
string cta = 3; // what the post asks people to do, in plain words
string why = 4; // why it matters to this person
string channel = 5; // instagram | youtube
}
// One finding a scenario is drawn from.
message ScenarioEvidence {
string ref = 1; // "E3"
string kind = 2; // site | offering | niche | trend | trending_post | competitor_channel | lead | persona | gap
string text = 3;
string source_url = 4; // "" when the finding has no page of its own
}
// One scenario. Contract with the campaign plan generator (Agent D): it reads
// the kept scenarios (withheld = false) and their items when present.
message ContentScenario {
string id = 1;
string audit_run_id = 2;
string persona = 3; // who it is for (from the tuning, the audit's leads or its audience)
string pain = 4; // the problem or job that person has
string angle = 5; // educate | proof | behind_the_scenes | offer | event
string offering = 6; // what the business sells that it serves (stated on the site or by the owner)
repeated string channel_formats = 7;
repeated string evidence_refs = 8; // refs into evidence
double score = 9; // 0-100: evidence strength and fit; ranks the list
bool withheld = 10;
string withheld_reason = 11;
repeated ScenarioItem items = 12;
repeated ScenarioEvidence evidence = 13;
// How the score was reached, in plain words ("3 findings, 2 measured; …").
string score_basis = 14;
// The plan gate's verdict: concur | unable | off ("" when withheld before it).
string verdict = 15;
// persona_source: tuning | leads | audience. offering_source: tuning | site.
string persona_source = 16;
string offering_source = 17;
// What PULSE's own web research found for it ("" = none ran or none found).
string research_note = 18;
// The Go checks' summary ("scenario-items 100/pass").
repeated string checks = 19;
}
// One day of the Instagram week (daily posting across several scenarios):
// no topic twice in a row, at most one offer post in any four.
message RotationSlot {
int32 day = 1; // 1..7
string scenario_id = 2;
int32 item_index = 3; // into that scenario's items
string format = 4;
string angle = 5;
string topic = 6; // the scenario's pain, for the rotation rule
bool promo = 7; // angle == offer
}
message ListContentScenariosRequest {
string audit_run_id = 1; // "" = the latest run with scenarios
}
message ListContentScenariosResponse {
string audit_run_id = 1;
string domain = 2;
// The run's content_scenarios stage: pending | running | done | failed |
// skipped ("" = no run), and its detail or error.
string stage_status = 3;
string stage_detail = 4;
repeated ContentScenario scenarios = 5;
// Derived from the measured inputs; run inside the time budget; not run
// because the budget could not pay for them (they are listed withheld).
int32 derived = 6;
int32 dispatched = 7;
int32 capped = 8;
string depth = 9; // quick | deep
repeated RotationSlot instagram_rotation = 10;
string generated_at = 11; // RFC 3339; "" = none yet
// The tuning the scenarios were built with.
ResearchTuning tuning = 12;
// Why there is no Instagram week ("" = there is one).
string rotation_note = 13;
// The hash-chain head over every scenario's outcome (runi/chain).
string trace_head = 14;
}
// What the person tunes the research with. Lists are plain words; an empty
// list or a 0 count means "not set", never "none".
message ResearchTuning {
string goal = 1;
repeated string personas = 2; // who they sell to
repeated string offerings = 3; // what they sell
repeated string channels = 4; // instagram | youtube
int32 posts_per_week = 5; // 0 = not set
int32 stories_per_day = 6; // 0 = not set
repeated string focus_topics = 7;
repeated string avoid_topics = 8;
string language = 9;
string region = 10;
string depth = 11; // quick | deep ("" = quick)
string updated_at = 12; // "" = never saved
bool saved = 13; // false: nothing saved yet (the seeds below still apply)
// What the latest audit found, offered as chips: never saved by itself.
repeated string seeded_personas = 14;
repeated string seeded_offerings = 15;
// The expertise Leads › Freelance searches with. Empty = PULSE infers it
// from the audit (seeded_expertise); saved = exactly these terms.
repeated string expertise = 16;
// What the latest audit inferred, offered as chips: never saved by itself.
repeated string seeded_expertise = 17;
}
message GetResearchTuningRequest {}
message SaveResearchTuningRequest {
ResearchTuning tuning = 1;
}
message RetuneContentScenariosRequest {
string audit_run_id = 1; // "" = the latest run
}
message RetuneContentScenariosResponse {
string audit_run_id = 1;
string status = 2; // started | running (already re-tuning)
string detail = 3;
}InsightsService
Prescriptive content intelligence — the analysis behind the Content Gaps, Content Strategy, and Strategy Roadmap surfaces. Each RPC is synthesized by the platform’s OWN sovereign model (no external AI), grounded in the user’s diagnosis + published content + live market signals, and returned as structured rows the limbic screens render directly (plus a summary and a single headline score).
pulse.v1.InsightsService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
AnalyzeContentGaps | AnalyzeContentGapsRequest → ContentGapsResponse | editor | AnalyzeContentGaps finds topics/formats the user under-serves vs. demand. |
GenerateContentStrategy | GenerateContentStrategyRequest → ContentStrategyResponse | editor | GenerateContentStrategy proposes content pillars, cadence, and themes. |
GenerateStrategyRoadmap | GenerateStrategyRoadmapRequest → StrategyRoadmapResponse | editor | GenerateStrategyRoadmap lays out a phased go-to-market roadmap. |
GetAuditContentGaps | GetAuditContentGapsRequest → AuditContentGaps | viewer | GetAuditContentGaps returns the content gaps computed after the caller’s latest audit, and that step’s progress. No model call. |
ListOwnInsights | ListOwnInsightsRequest → ListOwnInsightsResponse | viewer | ListOwnInsights lists what the caller ran by hand (AnalyzeContentGaps, GenerateContentStrategy), newest first, as stored. No model call. |
message GetAuditContentGapsRequest {}
message ListOwnInsightsRequest {}
// One result the user ran by hand; exactly one of gaps / strategy is set.
message OwnInsight {
string id = 1;
string kind = 2; // content_gaps | content_strategy
google.protobuf.Timestamp created_at = 3;
ContentGapsResponse gaps = 4;
ContentStrategyResponse strategy = 5;
}
message ListOwnInsightsResponse {
repeated OwnInsight insights = 1;
}
message AuditContentGaps {
// Unset when no audit has computed gaps yet.
ContentGapsResponse gaps = 1;
// The latest audit run ("" = the caller never ran one) and its domain.
string audit_run_id = 2;
string domain = 3;
// That run's content_gaps stage: pending | running | done | failed |
// skipped ("" = no run), and its detail or error.
string stage_status = 4;
string stage_detail = 5;
// The run whose gaps are shown, when it is an earlier one than audit_run_id.
string gaps_audit_run_id = 6;
// The campaign PULSE proposed from these gaps ("" = none).
string campaign_id = 7;
// Gaps that serve nothing the business sells (offering_match = no_match):
// kept out of gaps, offered as "doesn't match what you sell".
repeated ContentGap unmatched_gaps = 8;
}
message AnalyzeContentGapsRequest {
string focus_area = 1; // optional theme to concentrate the analysis on
DateRange date_range = 2; // window of published content to assess
// A competitor to compare with: its site (example.com) or a social handle
// (@name). A site is read; a handle is named only. "" = none.
string competitor = 3;
}
message ContentGap {
string topic = 1;
string format = 2; // e.g. "article", "video", "infographic"
double demand_score = 3; // 0-100 — how much the audience wants this
double coverage_score = 4; // 0-100 — how well the user currently covers it
double opportunity = 5; // 0-100 — prescriptive priority (demand vs coverage)
string rationale = 6;
// The judging ladder's verdict on this gap (cmd/judgement_gate.go): concur or
// unable-to-judge only — a dissented gap is withheld and appears only in
// ContentGapsResponse.judgements. Unset = judging off (PULSE_JUDGEMENT=off).
runink.ui.judgement.v1.Judgement judgement = 7;
// The audit findings this gap was drawn from. Empty = it cites none (the
// analysis was not run on an audit, or the model cited nothing that exists).
repeated GapEvidence evidence = 8;
// What the business sells that this gap serves, as the site or the owner
// states it ("" = none matched).
string offering = 9;
// matches | no_match | not_checked (no offerings were known).
string offering_match = 10;
}
// One audit finding a gap cites. The three scores of a gap are the model's
// estimates; evidence is what the audit measured.
message GapEvidence {
string ref = 1; // "E3"
string kind = 2; // site_score | check | discover | retention | trend | ai_visibility
string text = 3;
string source_url = 4; // "" when the finding has no page of its own
}
message ContentGapsResponse {
repeated ContentGap gaps = 1;
double coverage_index = 2; // headline: overall content coverage 0-100
string summary = 3;
google.protobuf.Timestamp generated_at = 4;
// Every verdict of this run, accepted AND rejected, with the ladder's counts.
runink.ui.judgement.v1.JudgementSet judgements = 5;
// What the check was asked (a manual check; "" = not asked).
string focus_area = 6;
string competitor = 7;
// How the competitor was used: "read" (its site's text was read) |
// "handle" (named only: a handle has no page PULSE reads) | "unreadable"
// (its site could not be read; competitor_reason says why) | "" (none).
string competitor_read = 8;
string competitor_reason = 9;
// How many of the latest audit's measured findings the check was given
// (0 = no audit to cite).
int32 audit_evidence_count = 10;
}
message GenerateContentStrategyRequest {
string objective = 1; // e.g. "Thought Leadership", "Lead Gen"
repeated Channel channels = 2;
string audience = 3;
}
message ContentPillar {
string name = 1;
string description = 2;
repeated string example_topics = 3;
double weight = 4; // recommended share of the content mix 0-100
// The judging ladder's verdict on this pillar; see ContentGap.judgement.
runink.ui.judgement.v1.Judgement judgement = 5;
}
message ContentStrategyResponse {
repeated ContentPillar pillars = 1;
string cadence = 2; // e.g. "3 posts/week, 1 long-form/month"
double alignment_score = 3; // headline: strategy-fit 0-100
string summary = 4;
google.protobuf.Timestamp generated_at = 5;
// Every verdict of this run, accepted AND rejected, with the ladder's counts.
runink.ui.judgement.v1.JudgementSet judgements = 6;
}
message GenerateStrategyRoadmapRequest {
string objective = 1;
int32 horizon_weeks = 2; // planning horizon (defaults sensibly when 0)
}
message RoadmapPhase {
string name = 1; // e.g. "Foundation", "Momentum", "Scale"
string timeframe = 2; // e.g. "Weeks 1-4"
repeated string initiatives = 3;
double momentum = 4; // projected momentum 0-100
string outcome = 5;
// The judging ladder's verdict on this phase; see ContentGap.judgement.
runink.ui.judgement.v1.Judgement judgement = 6;
}
message StrategyRoadmapResponse {
repeated RoadmapPhase phases = 1;
double readiness_score = 2; // headline 0-100
string summary = 3;
google.protobuf.Timestamp generated_at = 4;
// Every verdict of this run, accepted AND rejected, with the ladder's counts.
runink.ui.judgement.v1.JudgementSet judgements = 5;
}RadarService
Market research — trending topics, hashtag analysis, profile discovery.
pulse.v1.RadarService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
StartResearch | StartResearchRequest → stream StreamChunk | editor | StartResearch streams live market research findings for a given topic/niche. |
ListRadarResults | ListRadarResultsRequest → ListRadarResultsResponse | viewer | ListRadarResults returns the user’s stored radar results, most recent first — materialized from a diagnosis and produced by StartResearch. |
SuggestProfiles | SuggestProfilesRequest → SuggestProfilesResponse | editor | SuggestProfiles suggests influencer/competitor profiles to follow. |
UseRadarFeedback | UseRadarFeedbackRequest → google.protobuf.Empty | editor | UseRadarFeedback records user feedback on radar suggestions for refinement. |
GetTrendingPosts | GetTrendingPostsRequest → GetTrendingPostsResponse | editor | GetTrendingPosts returns real scraped social posts for a niche — a visual feed (image + source + relevance) rather than a text summary. |
SubmitPostFeedback | SubmitPostFeedbackRequest → google.protobuf.Empty | editor | SubmitPostFeedback records a like/dislike on a single trending post, distinct from UseRadarFeedback (which is profile-level) — this feedback is folded into the grounding context of future GetTrendingPosts calls. |
DiscoverCompetitorChannels | DiscoverCompetitorChannelsRequest → DiscoverCompetitorChannelsResponse | editor | DiscoverCompetitorChannels finds competitors’ YouTube & Instagram channels for a niche/competitor list via real web search + structured extraction. |
DiscoverGuestOpportunities | DiscoverGuestOpportunitiesRequest → DiscoverGuestOpportunitiesResponse | editor | DiscoverGuestOpportunities finds YouTube channels and podcasts the user could guest on (interview/collab formats) within a niche. |
DraftPartnershipOutreach | DraftPartnershipOutreachRequest → stream StreamChunk | editor | DraftPartnershipOutreach streams a first-contact message proposing a two-sided value exchange (e.g. a guest-episode swap) for a discovered channel/podcast, and stages it for the user’s approval (draft-only). |
ListPartnershipOutreach | ListPartnershipOutreachRequest → ListPartnershipOutreachResponse | viewer | ListPartnershipOutreach returns the outreach messages already drafted/staged. |
ListDiscoveredChannels | ListDiscoveredChannelsRequest → ListDiscoveredChannelsResponse | viewer | ListDiscoveredChannels returns the competitor channels and guest opportunities already discovered and persisted for the caller — by an audit’s background research pass or an earlier Discover* call — most relevant first. Read-only: it runs no search and no model call, so the Radar page can open on what the audit found instead of re-searching. |
ListTrendingPosts | ListTrendingPostsRequest → ListTrendingPostsResponse | viewer | ListTrendingPosts returns the trending posts already found and persisted for the caller, newest first. Read-only (no search, no model call). |
Also uses StreamChunk, Channel, AssistantToolEvent, AssistantProposal.
message StartResearchRequest {
string topic = 1;
string niche = 2;
repeated Channel channels = 3;
string target_audience = 4;
string region = 5; // e.g. "BR", "US", "LATAM"
string language = 6; // e.g. "pt-BR", "en-US"
// Extra sources the user attached to ground this research beyond the default
// web search — web-search seeds, website/YouTube URLs, or pasted text. The
// radar agent folds these into the prompt as user-provided grounding.
repeated ExtraSource extra_sources = 7;
}
// Where an ExtraSource came from — mirrors the "add sources" composer in the UI.
enum ExtraSourceKind {
EXTRA_SOURCE_KIND_UNSPECIFIED = 0;
EXTRA_SOURCE_KIND_WEB = 1; // a web-search seed (query grounded live)
EXTRA_SOURCE_KIND_WEBSITE = 2; // a website or YouTube URL to scrape
EXTRA_SOURCE_KIND_PASTED_TEXT = 3; // free-form text pasted by the user
}
// One user-attached source that grounds market research. `url` is set for
// website/YouTube sources (scraped server-side); `content` carries inline text
// for pasted-text sources; `label` is a human title shown as a chip in the UI.
message ExtraSource {
ExtraSourceKind kind = 1;
string label = 2; // display title (page title, "Pasted text", the query…)
string url = 3; // for website/YouTube sources
string content = 4; // inline text for pasted-text sources
}
message ListRadarResultsRequest {}
message ListRadarResultsResponse {
repeated RadarResults results = 1;
}
message RadarResults {
string id = 1;
string topic = 2;
repeated TrendingTopic trends = 3;
repeated HashtagCluster hashtag_clusters = 4;
repeated ProfileSuggestion suggested_profiles = 5;
string market_summary = 6;
string competitive_intel = 7;
google.protobuf.Timestamp generated_at = 8;
}
message TrendingTopic {
string title = 1;
string description = 2;
double relevance_score = 3; // 0.0-1.0
string source = 4; // platform or data source
repeated Channel channels = 5;
}
message HashtagCluster {
string primary_hashtag = 1;
repeated string related_hashtags = 2;
int64 estimated_reach = 3;
double engagement_rate = 4;
Channel channel = 5;
}
message ProfileSuggestion {
string username = 1;
string display_name = 2;
string bio = 3;
string profile_url = 4;
Channel channel = 5;
int64 follower_count = 6; // as stated in the search results; 0 = unknown (never estimated)
double relevance_score = 7;
string category = 8; // "influencer", "competitor", "partner"
}
message SuggestProfilesRequest {
string niche = 1;
repeated Channel channels = 2;
string region = 3;
int32 max_results = 4;
}
message SuggestProfilesResponse {
repeated ProfileSuggestion profiles = 1;
}
message UseRadarFeedbackRequest {
string research_id = 1;
string profile_username = 2;
string feedback_type = 3; // "useful", "not_relevant", "save", "block"
string notes = 4;
}
// RadarPost is one real scraped social/web post surfaced by GetTrendingPosts
// — a visual feed item (image + source + a 0-100 relevance/hot score) that
// the user can react to, as opposed to a text-only TrendingTopic summary.
message RadarPost {
string id = 1;
string source_url = 2;
string image_url = 3;
string caption = 4;
string author_handle = 5;
Channel channel = 6;
int32 hot_score = 7; // 0-100, the model's estimate; -1 = not scored
string feedback = 8; // "", "like", "dislike"
google.protobuf.Timestamp created_at = 9;
string niche = 10; // the niche the search ran for
}
message GetTrendingPostsRequest {
string niche = 1;
repeated Channel channels = 2;
int32 max_results = 3;
}
message GetTrendingPostsResponse {
repeated RadarPost posts = 1;
}
message SubmitPostFeedbackRequest {
string post_id = 1;
string feedback = 2; // "like" or "dislike"
}
// DiscoveredChannel is a competitor's social channel or a guest opportunity
// (YouTube channel / podcast) surfaced by Radar discovery.
message DiscoveredChannel {
string id = 1;
string name = 2; // channel / show / person name
string handle = 3; // @handle or host name
Channel channel = 4; // YOUTUBE, INSTAGRAM, PODCAST, ...
string url = 5; // channel / show URL
string description = 6; // what the channel is about
int64 audience_size = 7; // subscribers/followers/listeners as stated in the search results; 0 = unknown (never estimated)
string category = 8; // "competitor" or "guest_opportunity"
double relevance_score = 9; // 0.0-1.0 fit for the niche
string contact_hint = 10; // booking/contact link or email if found, else ""
google.protobuf.Timestamp created_at = 11;
// source_url is the channel URL ONLY when that URL appeared verbatim in the
// web-search results the discovery was grounded on; "" when the model
// produced a URL the search never returned (unverified — never imported as
// an influencer, and shown as unverified).
string source_url = 12;
google.protobuf.Timestamp discovered_at = 13; // when it was found and persisted
string niche = 14; // the niche it was found for
// true = relevance_score could not be read (the model wrote no number):
// the fit is ABSENT and shown as "not rated", never as 0.
bool relevance_unrated = 15;
}
message DiscoverCompetitorChannelsRequest {
string niche = 1;
repeated string competitors = 2; // explicit names; if empty, derived from niche/diagnosis
string region = 3;
int32 max_results = 4;
}
message DiscoverCompetitorChannelsResponse {
repeated DiscoveredChannel channels = 1;
}
message DiscoverGuestOpportunitiesRequest {
string niche = 1;
string topic = 2; // what the user wants to be a guest about
repeated Channel channels = 3; // restrict to e.g. YOUTUBE, PODCAST; empty = both
string region = 4;
int32 max_results = 5;
}
message DiscoverGuestOpportunitiesResponse {
repeated DiscoveredChannel channels = 1;
}
// PartnershipOutreach is a staged first-contact message for a discovered
// channel/podcast, proposing a two-sided value exchange. Draft-only until the
// user reviews and sends it (no auto-send).
message PartnershipOutreach {
string id = 1;
string channel_id = 2; // DiscoveredChannel.id it targets (may be "")
string target_name = 3;
string target_url = 4;
Channel channel = 5;
string subject = 6;
string body = 7;
string value_for_them = 8; // why the host benefits
string value_for_us = 9; // why we benefit
string status = 10; // "draft"
google.protobuf.Timestamp created_at = 11;
}
message DraftPartnershipOutreachRequest {
string channel_id = 1; // discovered channel to target (optional)
string target_name = 2; // required if channel_id empty
string target_url = 3;
Channel channel = 4;
string category = 5; // "competitor" | "guest_opportunity"
string angle = 6; // optional extra context / offer angle
}
message ListPartnershipOutreachRequest {
int32 max_results = 1;
}
message ListPartnershipOutreachResponse {
repeated PartnershipOutreach outreach = 1;
}
message ListDiscoveredChannelsRequest {
string category = 1; // "competitor" | "guest_opportunity"; "" = both
int32 max_results = 2; // <= 0 = server default (50)
}
message ListDiscoveredChannelsResponse {
repeated DiscoveredChannel channels = 1;
}
message ListTrendingPostsRequest {
string niche = 1; // "" = every niche the caller has researched
int32 max_results = 2; // <= 0 = server default (20)
}
message ListTrendingPostsResponse {
repeated RadarPost posts = 1;
}SearchConsoleService
Google Search Console, read-only (scope webmasters.readonly): connect with Google (the same OAuth client as YouTube, PKCE), pick the property, and read the Search Analytics of the last 28 days against the 28 before, once a day. What it reads is measured search demand: clicks, impressions, CTR and average position per query and per page. Not connected = not measured.
pulse.v1.SearchConsoleService, declared in search_console.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
StartSearchConsoleConnect | StartSearchConsoleConnectRequest → StartSearchConsoleConnectResponse | editor | StartSearchConsoleConnect returns Google’s consent URL; Google redirects to /oauth/search-console/callback, which seals the tokens and lists the properties. configured=false (with message) when this server has no Google client or no public address. |
GetSearchConsole | GetSearchConsoleRequest → SearchConsoleStatus | viewer | GetSearchConsole: the connection, its properties and its last read. |
SetSearchConsoleProperty | SetSearchConsolePropertyRequest → SearchConsoleStatus | editor | SetSearchConsoleProperty chooses the property PULSE reads. |
SyncSearchConsole | SyncSearchConsoleRequest → SearchConsoleStatus | editor | SyncSearchConsole reads now (the daily read does the same; a read that already has today’s data makes no call). |
GetSearchVisibility | GetSearchVisibilityRequest → SearchVisibility | viewer | GetSearchVisibility: what was read, for Brand Analysis. A read; no call to Google. |
message StartSearchConsoleConnectRequest {
bool reconnect = 1;
}
message StartSearchConsoleConnectResponse {
bool configured = 1;
string authorize_url = 2;
string redirect_uri = 3; // the callback the Google OAuth client must allow
string message = 4; // why sign-in is not available, when configured=false
}
// A Search Console property the connected Google account can read.
message SearchConsoleProperty {
string site_url = 1; // "sc-domain:example.com" or "https://www.example.com/"
string permission_level = 2; // siteOwner | siteFullUser | siteRestrictedUser
bool matches_audited_domain = 3;
}
message GetSearchConsoleRequest {}
message SetSearchConsolePropertyRequest {
string site_url = 1;
}
message SyncSearchConsoleRequest {}
message SearchConsoleStatus {
// not_connected | pick_property | connected | reconnect
string state = 1;
string integration_id = 2;
string account_name = 3;
string site_url = 4; // the chosen property; "" when none
repeated SearchConsoleProperty properties = 5;
string audited_domain = 6; // the domain of the latest site audit; "" when none
string properties_note = 7; // why the property list is empty, when it is
string watermark = 8; // last day read (YYYY-MM-DD); "" = never read
google.protobuf.Timestamp last_read_at = 9;
string last_error = 10;
string last_error_kind = 11; // auth | permission | quota | unreadable; "" when the last read worked
}
message GetSearchVisibilityRequest {
int32 limit = 1; // rows per list; 0 = 10
}
// One query or page, last 28 days, with the 28 before when it had any.
message SearchRow {
string key = 1; // the query, or the page URL
int64 clicks = 2;
int64 impressions = 3;
double ctr = 4; // 0..1
double position = 5; // average position, 1 = top
bool has_prior = 6;
int64 prior_clicks = 7;
int64 prior_impressions = 8;
double prior_position = 9;
}
message SearchVisibility {
// False: nothing was read (why says so: not connected, no property, not
// read yet, or the last read failed). Never shown as zero.
bool measured = 1;
string why = 2;
string site_url = 3;
string current_start = 4; // YYYY-MM-DD
string current_end = 5;
string prior_start = 6;
string prior_end = 7;
// Totals over the days read in each window; has_totals false when the days
// were not read.
bool has_totals = 8;
int64 clicks = 9;
int64 impressions = 10;
bool has_prior_totals = 11;
int64 prior_clicks = 12;
int64 prior_impressions = 13;
repeated SearchRow top_queries = 14; // most clicks first
repeated SearchRow losing_pages = 15; // most clicks lost first
repeated SearchRow near_page_one = 16; // average position 4 to 15, most impressions first
google.protobuf.Timestamp read_at = 17;
}GoogleBusinessService
Google Business Profile (GBP), per account: connect with Google (the same OAuth client as YouTube and Search Console, PKCE, scope business.manage), choose the locations PULSE manages, and read their reviews and basic performance. Replies to reviews are DRAFTED by PULSE’s own inference into an approval queue; only a person’s approval posts one, and a negative review is never answered without the person saying they read it. GBP posts (update, offer, event) are content on CHANNEL_GOOGLE_BUSINESS: they go through the approval queue and the publisher like every other channel (PULSE_APPLY_ENABLED and PULSE_PUBLISH_GBP; replies also PULSE_PUBLISH_GBP_REPLIES). Not connected = not measured, never a zero.
pulse.v1.GoogleBusinessService, declared in gbp.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
StartGBPConnect | StartGBPConnectRequest → StartGBPConnectResponse | editor | StartGBPConnect returns Google’s consent URL; Google redirects to /oauth/google-business/callback, which seals the tokens and lists the locations. configured=false (with message) when this server has no Google client or no https public address. |
GetGBP | GetGBPRequest → GBPStatus | viewer | GetGBP: the connection, its locations and the last read. |
SetGBPLocations | SetGBPLocationsRequest → GBPStatus | editor | SetGBPLocations chooses the locations PULSE manages (reads, drafts replies for, and can post to). |
SyncGBP | SyncGBPRequest → GBPStatus | editor | SyncGBP reads now (the scheduled read does the same). |
ListGBPReviews | ListGBPReviewsRequest → GBPReviews | viewer | ListGBPReviews: what was read, for the Reviews page. No call to Google. |
ApproveGBPReply | ApproveGBPReplyRequest → GBPReview | editor | ApproveGBPReply posts the reply (as drafted, or the person’s edit) through every publish gate. A negative review needs acknowledge_negative=true. |
DismissGBPReply | DismissGBPReplyRequest → GBPReview | editor | DismissGBPReply drops the draft: nothing is posted. |
CreateGBPPost | CreateGBPPostRequest → CreateGBPPostResponse | editor | CreateGBPPost saves a GBP post as content waiting for approval on CHANNEL_GOOGLE_BUSINESS. Approving it in the approval queue publishes it. |
ProposeReviewRequest | ProposeReviewRequestRequest → ProposeReviewRequestResponse | editor | ProposeReviewRequest drafts a review-request email for a won lead in the outreach system (the same proposal PULSE makes when a deal is marked won). It waits for approval like every outreach email. |
message StartGBPConnectRequest {
bool reconnect = 1;
}
message StartGBPConnectResponse {
bool configured = 1;
string authorize_url = 2;
string redirect_uri = 3; // the callback the Google OAuth client must allow
string message = 4; // why sign-in is not available, when configured=false
}
// A Business Profile location the connected Google account manages.
message GBPLocation {
string name = 1; // "locations/123"
string account = 2; // "accounts/456"
string title = 3;
string address = 4;
string place_id = 5; // "" when Google gave none (no review link then)
string maps_uri = 6;
string review_uri = 7; // the link that opens "write a review"; "" when unknown
bool managed = 8; // PULSE reads it and drafts for it
}
message GetGBPRequest {}
message SetGBPLocationsRequest {
repeated string names = 1; // the managed locations; empty = none
}
message SyncGBPRequest {}
message GBPStatus {
// not_connected | pick_locations | connected | reconnect
string state = 1;
string integration_id = 2;
string account_name = 3;
repeated GBPLocation locations = 4;
string locations_note = 5; // why the list is empty, when it is
google.protobuf.Timestamp last_read_at = 6;
string last_error = 7;
string last_error_kind = 8; // auth | permission | quota | unreadable; "" when the last read worked
}
message ListGBPReviewsRequest {
string location_name = 1; // "" = every managed location
}
message GBPReview {
string id = 1; // PULSE's id
string location_name = 2;
string location_title = 3;
string reviewer = 4; // "" for an anonymous reviewer
int32 rating = 5; // 1..5; 0 = Google gave no star rating
string text = 6; // "" = a rating with no text
google.protobuf.Timestamp created_at = 7;
bool has_reply = 8; // the business has replied on Google
string reply_text = 9;
// none | not_drafted | waiting | sent | withheld | failed | dismissed
string draft_status = 10;
string draft_reply = 11;
string draft_reason = 12; // why not drafted, withheld or failed
bool negative = 13; // 1-2 stars, or 3 stars with a complaint: never answered without the person
}
// Basic performance of the managed locations, last 28 complete days. Each
// figure counts only when its *_reported flag is true (Google reported it).
message GBPInsights {
bool measured = 1;
string why = 2; // when not measured
string start = 3; // YYYY-MM-DD
string end = 4;
bool impressions_reported = 5;
int64 impressions = 6; // Search + Maps, desktop + mobile
bool calls_reported = 7;
int64 calls = 8;
bool website_clicks_reported = 9;
int64 website_clicks = 10;
bool direction_requests_reported = 11;
int64 direction_requests = 12;
}
message GBPReviews {
// False: nothing was read (why says so). Never shown as zero.
bool measured = 1;
string why = 2;
bool has_rating = 3; // Google reported an average rating
double average_rating = 4; // weighted over the managed locations
int64 total_reviews = 5; // as Google counts them
int32 unanswered = 6; // of the stored reviews
int32 waiting_approval = 7; // drafts waiting for a person
repeated GBPReview reviews = 8; // newest first
GBPInsights insights = 9;
google.protobuf.Timestamp read_at = 10;
}
message ApproveGBPReplyRequest {
string review_id = 1;
string text = 2; // "" = as drafted
bool acknowledge_negative = 3; // required for a negative review
}
message DismissGBPReplyRequest {
string review_id = 1;
}
message CreateGBPPostRequest {
string location_name = 1;
string topic_type = 2; // update | offer | event
string summary = 3; // the post's text (Google allows 1500 characters)
string event_title = 4; // event and offer
string start_date = 5; // YYYY-MM-DD, event and offer
string end_date = 6; // YYYY-MM-DD, event and offer
string coupon_code = 7; // offer, optional
string redeem_url = 8; // offer, optional
string terms = 9; // offer, optional
string action_type = 10; // "" | LEARN_MORE | BOOK | ORDER | SHOP | SIGN_UP | CALL
string action_url = 11; // required for every action but CALL
string campaign_id = 12; // optional
}
message CreateGBPPostResponse {
string content_id = 1;
}
message ProposeReviewRequestRequest {
string lead_id = 1;
}
message ProposeReviewRequestResponse {
string sequence_id = 1;
string message = 2;
}BrandSignalsService
SERVICE: BrandSignalsService (owner, 2026-11-16)
Brand awareness (how visible and mentioned the brand is), Reputation (reviews and public comment) and Customer approvals (how customers approve of the brand and its offers). All three are computed by the platform’s ONE market-signals engine (org-runink/crawler signals), shared with FACE: public search through the shared crawler (robots obeyed), PULSE’s own model behind the untrusted-data fence, cited cards only. PULSE stores each week’s measures, compares the latest week with the account’s OWN earlier weeks (no fixed threshold; confidence n/(n+1)), and turns a shift into a campaign PROPOSAL a person accepts or dismisses in Campaigns. Nothing is published or sent. Reviews are themes, never people.
pulse.v1.BrandSignalsService, declared in brand_signals.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
GetBrandSignals | GetBrandSignalsRequest → BrandSignals | viewer | What is stored for one area: the last reading, the measures’ weeks and the ideas. No search and no model. |
ReadBrandSignals | ReadBrandSignalsRequest → BrandSignals | editor | Read one area now (search + model); the week’s measures are stored. |
ProposeBrandCampaign | ProposeBrandCampaignRequest → ProposeBrandCampaignResponse | editor | Turn one idea into a campaign PROPOSAL (Campaigns: accept or dismiss). |
enum BrandArea {
BRAND_AREA_UNSPECIFIED = 0;
BRAND_AREA_AWARENESS = 1;
BRAND_AREA_REPUTATION = 2;
BRAND_AREA_APPROVAL = 3;
}
message GetBrandSignalsRequest {
BrandArea area = 1;
}
message ReadBrandSignalsRequest {
BrandArea area = 1;
}
message ProposeBrandCampaignRequest {
BrandArea area = 1;
string idea_id = 2;
}
message ProposeBrandCampaignResponse {
string campaign_id = 1;
// Set when nothing new was proposed, and why.
string note = 2;
}
message BrandSignalEvidence {
string excerpt = 1;
string source_url = 2;
string source_label = 3;
}
message BrandSignalCard {
string kind = 1;
// positive | negative | mixed | neutral
string tone = 2;
string title = 3;
string summary = 4;
string suggestion = 5;
// low | medium | high, and why.
string confidence = 6;
string confidence_reason = 7;
repeated BrandSignalEvidence evidence = 8;
}
message BrandSignalSource {
string label = 1;
string url = 2;
// read | not_readable | not_configured | failed
string state = 3;
string note = 4;
}
// One week's value of a measure.
message BrandMeasureWeek {
string week = 1; // YYYY-MM-DD, a Monday
double value = 2;
int32 basis = 3;
}
// One measure: its latest value, what it rests on, and its own history.
message BrandMeasure {
// visibility | mentions | rating | positive_share | approval
string name = 1;
double value = 2;
// What the value rests on (pages, reviews, cited pieces); 0 = not measured.
int32 basis = 3;
// Why it was not measured, when basis is 0.
string note = 4;
// Oldest first; weeks with basis 0 are left out.
repeated BrandMeasureWeek weeks = 5;
}
// A campaign idea from a measure's shift in its latest week against the
// account's own earlier weeks.
message BrandCampaignIdea {
string idea_id = 1;
string measure = 2;
// up | down
string direction = 3;
string week = 4;
double this_week = 5;
double earlier_mean = 6;
double earlier_min = 7;
double earlier_max = 8;
int32 earlier_weeks = 9;
// n / (n + 1) for n earlier weeks.
double confidence = 10;
string confidence_reason = 11;
// The English rationale the proposal records.
string rationale = 12;
// Oldest first; the last is this week.
repeated BrandMeasureWeek evidence = 13;
// The campaign proposed from it ("" = not proposed).
string campaign_id = 14;
}
message BrandSignals {
BrandArea area = 1;
// no_brand (no check-up names the brand) | not_read | read
string state = 2;
string brand_name = 3;
// Why there are no cards, when there are none.
string note = 4;
google.protobuf.Timestamp read_at = 5;
repeated BrandSignalCard cards = 6;
repeated BrandSignalSource sources = 7;
repeated BrandMeasure measures = 8;
repeated BrandCampaignIdea ideas = 9;
// Why there are no ideas (e.g. no earlier week yet).
string ideas_note = 10;
// Reputation and approvals: whether reviews PULSE holds were included.
bool reviews_included = 11;
}SiteChatService
The account owner’s side of the WEBSITE CHAT: the PULSE assistant in a public website-visitor mode (cmd/site_chat*.go). The visitor side is plain HTTP under /site-chat/ (a static widget plus JSON), authenticated by the site key these RPCs make, pinned to the listed origins. A visitor sees only the account’s public facts (offerings, approved FAQ content, pages of its own site); never leads, plans, metrics, other chats or internal tools.
pulse.v1.SiteChatService, declared in site_chat.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
GetSiteChat | GetSiteChatRequest → SiteChatSettings | viewer | |
UpdateSiteChat | UpdateSiteChatRequest → SiteChatSettings | editor | Saves on/off, origins, greeting and language. Turning it on the first time makes the site key. |
RotateSiteChatKey | RotateSiteChatKeyRequest → SiteChatSettings | editor | A new site key; the old one stops working at once. |
RevokeSiteChatKey | RevokeSiteChatKeyRequest → SiteChatSettings | editor | No key at all: the widget stops answering and the chat is off. |
ListSiteChatHandoffs | ListSiteChatHandoffsRequest → ListSiteChatHandoffsResponse | viewer | “Ask a person” requests from visitors, newest first. |
ResolveSiteChatHandoff | ResolveSiteChatHandoffRequest → SiteChatHandoff | editor |
message GetSiteChatRequest {}
message SiteChatSettings {
bool enabled = 1;
// The public site key the snippet carries. Not a secret (it is in the
// page), but only ever lets a visitor chat with this account's public facts
// from the listed origins. "" = none (revoked or never made).
string site_key = 2;
repeated string allowed_origins = 3;
string greeting = 4;
string language = 5; // en | es | fr | pt: the widget's language
// The HTML to paste just before the closing body tag; "" without a key
// or a public URL.
string embed_snippet = 6;
// The widget script's URL (PULSE_PUBLIC_BASE_URL + /site-chat/widget.js).
string widget_url = 7;
// False: this server has no rate limits, daily cap or public URL set, so
// the widget answers nothing; why lists what is missing.
bool server_ready = 8;
string server_not_ready_why = 9;
// How long a visitor's chat is kept, in hours (PULSE_SITE_CHAT_RETENTION_HOURS).
int32 retention_hours = 10;
// Visitor messages accepted today (UTC) against the daily cap.
int32 messages_today = 11;
int32 daily_cap = 12;
google.protobuf.Timestamp key_created_at = 13;
}
message UpdateSiteChatRequest {
bool enabled = 1;
repeated string allowed_origins = 2;
string greeting = 3;
string language = 4;
}
message RotateSiteChatKeyRequest {}
message RevokeSiteChatKeyRequest {}
message SiteChatTurn {
string role = 1; // user (the visitor) | assistant
string text = 2;
google.protobuf.Timestamp at = 3;
}
message SiteChatHandoff {
string id = 1;
string status = 2; // open | resolved
string message = 3; // what the visitor asked a person
// Given only with the visitor's consent; "" otherwise.
string name = 4;
string email = 5;
string page = 6; // host + path the visitor was on
google.protobuf.Timestamp created_at = 7;
google.protobuf.Timestamp resolved_at = 8;
// The visitor's chat while it is kept (see retention_hours); empty after.
repeated SiteChatTurn transcript = 9;
string lead_id = 10; // the lead made from it, when the visitor consented
}
message ListSiteChatHandoffsRequest {
bool open_only = 1;
}
message ListSiteChatHandoffsResponse {
repeated SiteChatHandoff handoffs = 1;
}
message ResolveSiteChatHandoffRequest {
string id = 1;
}SiteRepoService
The person’s own website repository on GitHub (Settings → Integrations → Website repository) and the site fixes PULSE proposes there as pull requests. Proposals go through the GitHub REST API only. PULSE never pushes to the base branch and never merges: a pull request is a proposal. Proposing needs PULSE_APPLY_ENABLED + PULSE_AUDIT_APPLY and an admin.
pulse.v1.SiteRepoService, declared in site_repo.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
GetSiteRepo | GetSiteRepoRequest → SiteRepo | viewer | The stored connection and its last checked status. Dials nothing. |
ConnectSiteRepo | ConnectSiteRepoRequest → SiteRepo | editor | Stores the repository (token sealed) and checks access. Admin only. |
CheckSiteRepo | CheckSiteRepoRequest → SiteRepo | editor | Checks access again and stores the answer. |
DisconnectSiteRepo | DisconnectSiteRepoRequest → google.protobuf.Empty | editor | Forgets the repository and its token. Admin only. |
ProposeSiteFix | ProposeSiteFixRequest → SiteProposal | editor | Proposes one audit fix as one branch and one pull request. |
ListSiteProposals | ListSiteProposalsRequest → ListSiteProposalsResponse | viewer | The proposals of a run as last read. |
RefreshSiteProposals | ListSiteProposalsRequest → ListSiteProposalsResponse | editor | Reads each proposal’s pull request state back from GitHub. |
enum SiteRepoStatus {
SITE_REPO_STATUS_UNSPECIFIED = 0;
SITE_REPO_STATUS_NOT_CONNECTED = 1;
SITE_REPO_STATUS_CONNECTED = 2;
SITE_REPO_STATUS_MISSING_PERMISSION = 3;
SITE_REPO_STATUS_UNREACHABLE = 4;
SITE_REPO_STATUS_TOKEN_REJECTED = 5;
SITE_REPO_STATUS_BRANCH_NOT_FOUND = 6;
}
message SiteRepo {
string owner = 1;
string repo = 2;
string base_branch = 3;
SiteRepoStatus status = 4;
string status_detail = 5; // why, in plain words; "" when connected
google.protobuf.Timestamp checked_at = 6; // unset = never checked
bool has_token = 7;
}
message GetSiteRepoRequest {}
message ConnectSiteRepoRequest {
string owner = 1;
string repo = 2;
string base_branch = 3; // "" = main
// A fine-grained personal access token limited to this repository with
// Contents and Pull requests read and write. "" keeps the stored token.
string token = 4;
}
message CheckSiteRepoRequest {}
message DisconnectSiteRepoRequest {}
message ProposeSiteFixRequest {
string run_id = 1; // the audit run whose site score found the issue
string check_id = 2; // the finding (AuditAction.check_id)
}
message SiteProposalFile {
string path = 1;
string op = 2; // create | modify
string reason = 3;
}
message SiteProposal {
string id = 1;
string run_id = 2;
string check_id = 3;
// open | merged | closed (read from GitHub); not_needed (the fix is already
// in the repository or cannot be placed; detail says which); withheld (the
// plan gate dissented; detail says why).
string state = 4;
string detail = 5;
string branch = 6;
int32 pr_number = 7;
string pr_url = 8;
string stack = 9;
repeated SiteProposalFile files = 10;
google.protobuf.Timestamp created_at = 11;
google.protobuf.Timestamp state_checked_at = 12;
// The plan gate's verdict: concur | unable | off.
string gate = 13;
}
message ListSiteProposalsRequest {
string run_id = 1;
}
message ListSiteProposalsResponse {
repeated SiteProposal proposals = 1;
}