{ "openapi": "3.1.0", "info": { "title": "Anchored Growth Public API", "description": "Anchored Growth is an outbound intelligence platform that turns real outreach outcomes into calibrated, drift-aware decisions for AI sales agents. This tenant-scoped read API exposes the pre-computed campaign pattern analysis, recipient intelligence, and per-contact decision history behind those recommendations. Every endpoint is scoped to the company identified by the caller's API key; there is no way to read another tenant's data. All successful responses use a common envelope: {\"success\": true, \"message\": \"...\", \"data\": , \"timestamp\": \"\"}. Authenticate with a self-serve `ag_` API key sent as `Authorization: Bearer ag_...` or in the `X-API-Key` header (never in the query string). Self-serve keys are subject to a burst rate limit (default 200 requests per 15-minute window) and a monthly quota (default 1,000 requests); exceeding either returns 429.\n\nRate limits: every response carries RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers (burst window, default 200 requests per 15 minutes per key); 429 responses include Retry-After, and rejected calls do not consume monthly quota. Versioning: the API is versioned in the URL path (/v1); within a major version changes are additive only. Deprecations are announced at least 90 days ahead via Deprecation and Sunset headers (RFC 8594) and email to key holders \u2014 policy: https://anchoredgrowth.io/developers#api-policies", "version": "1.0.0", "contact": { "email": "contact@anchoredgrowth.io" } }, "servers": [ { "url": "https://api.anchoredgrowth.io/v1", "description": "Production. The /v1 base path maps to the API root, so operation paths below are relative to it (e.g. GET https://api.anchoredgrowth.io/v1/patterns)." } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Patterns", "description": "Pre-computed message pattern analysis: what tones, subjects, timing, and content structures actually get replies for this company." }, { "name": "Intelligence", "description": "Per-contact decision history from the Anchored Growth workflow intelligence engine." }, { "name": "System", "description": "Service health and API key verification." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "System" ], "summary": "Health check and API key verification", "description": "Verifies service availability and validates the supplied API key in one call. When a valid key is provided, the response echoes back the authenticated company context (companyId, permissions), current rate-limit standing, and per-dependency service status. An agent should call this once at startup to confirm its credentials work and to learn its remaining rate-limit budget before making data calls. Note: although this endpoint is exempt from the global security requirement for discovery purposes, the handler still validates any supplied credentials and returns 401 when the key is missing or invalid.", "security": [], "responses": { "200": { "description": "Service is healthy and the API key authenticated successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Human-readable status, e.g. \"API key authentication successful - service is healthy\"." }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Overall service status.", "enum": [ "healthy" ] }, "service": { "type": "string", "description": "Service name: \"Anchored Growth Public API\"." }, "version": { "type": "string", "description": "API version string." }, "timestamp": { "type": "string", "format": "date-time" }, "authentication": { "type": "object", "description": "Echo of the authenticated caller's context.", "properties": { "companyId": { "type": "string", "description": "Tenant company ID resolved from the API key." }, "portalId": { "type": [ "string", "null" ], "description": "HubSpot portal ID when portal-based auth was used; null for self-serve ag_ keys." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this key (e.g. analytics_read)." }, "authenticated": { "type": "boolean", "const": true } } }, "rateLimiting": { "type": "object", "properties": { "remaining": { "type": [ "integer", "null" ], "description": "Requests remaining in the current window." }, "windowMinutes": { "type": "integer", "description": "Rate-limit window length in minutes (default 15)." }, "maxRequests": { "type": "integer", "description": "Maximum requests per window (default 1000)." } } }, "services": { "type": "object", "properties": { "database": { "type": "string", "description": "\"operational\" or \"degraded\"." }, "rateLimit": { "type": "string" }, "audit": { "type": "string" } } }, "environment": { "type": "object", "properties": { "stage": { "type": "string" }, "region": { "type": "string" } } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns": { "get": { "operationId": "getPatterns", "tags": [ "Patterns" ], "summary": "List message pattern recommendations", "description": "Returns the company's pre-computed message pattern recommendations, sorted by tier (highest first). Each record is a stored recommendation from the intelligence pipeline \u2014 for example a tone, timing, or content pattern with an observed lift. An agent should call this to get the current ranked set of actionable outreach recommendations for the tenant before composing or scheduling messages. Returns an empty array when no analysis has been generated yet.", "responses": { "200": { "description": "Array of pattern recommendation records (may be empty).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "array", "description": "Stored recommendation records from the intelligence pipeline, sorted by tier descending. May be empty when no analysis has been generated yet.", "items": { "type": "object", "description": "A stored pattern recommendation record from the intelligence pipeline's ai-recommendations table (written by the intelligence service's writeRecommendations). Base fields come from the recommendation catalog (code, title, type, message, positive, tier) with template values substituted; the writer stamps companyId and updated. Metric analyzers may attach extra fields (e.g. evidence_tier, metric, description); fallback observation records (codes ending in -OBS-*) omit type. The message/title strings may contain HTML markup.", "additionalProperties": true, "required": [ "companyId", "code" ], "properties": { "companyId": { "type": "string", "description": "Tenant company ID (table partition key)." }, "code": { "type": "string", "description": "Pattern code and table sort key, e.g. TA-1, DOW-2, BWC-OBS-1." }, "title": { "type": "string", "description": "Display title (template-substituted; may contain HTML)." }, "message": { "type": "string", "description": "Recommendation text (template-substituted; may contain HTML)." }, "type": { "type": "string", "description": "Catalog record type, e.g. \"recommendation\". Absent on fallback observation records." }, "positive": { "type": "boolean", "description": "Whether the pattern is a positive (do-more-of-this) recommendation." }, "tier": { "type": "number", "description": "Ranking tier; higher tiers indicate stronger evidence. Results are sorted by tier descending." }, "updated": { "type": "string", "description": "ISO 8601 timestamp stamped when the record was last written." }, "evidence_tier": { "type": "string", "description": "Evidence tier label attached by the estimation layer for lean-style recommendations (e.g. confirmed, likely, directional). Present only on records that carry it." }, "metric": { "type": "string", "description": "Human-readable metric/strategy string attached by some analyzers (e.g. tone strategy summaries). Present only on records that carry it." } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/descriptions": { "get": { "operationId": "getPatternDescriptions", "tags": [ "Patterns" ], "summary": "Get narrative pattern descriptions", "description": "Returns human-readable descriptions of the company's message patterns, produced by the analytics service (this endpoint proxies an internal analytics Lambda). Use it when an agent needs prose explanations of the patterns \u2014 for display to a user or as context for message drafting \u2014 rather than the raw recommendation records from GET /patterns. The payload is a passthrough of the analytics service's response.", "responses": { "200": { "description": "Pattern description payload from the analytics service.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true, "description": "Analytics-service envelope flag (always true on a 200)." }, "data": { "type": "object", "description": "Map of pattern code (e.g. DOW-2, TA-1, BWC-1) to its description entry. 51 codes in the current catalog.", "additionalProperties": { "type": "object", "description": "Narrative description of one pattern code, from the analytics service's static descriptions catalog (descriptions.json).", "additionalProperties": true, "required": [ "description", "category", "analysis", "type" ], "properties": { "description": { "type": "array", "items": { "type": "string" }, "description": "Ordered paragraphs explaining when the recommendation fires and how to act on it." }, "category": { "type": "array", "items": { "type": "string" }, "description": "Category path, e.g. [\"general\", \"day_of_week\"]." }, "analysis": { "type": "array", "items": { "type": "string" }, "description": "Which analysis series the pattern is derived from, e.g. [\"days\"], [\"hourly\"]." }, "type": { "type": "string", "description": "Chart/dimension type for the pattern, e.g. day, hour, range, tone." }, "chartType": { "type": "string", "description": "Preferred chart rendering (present on tone codes only), e.g. \"bar\"." }, "note": { "type": "string", "description": "Additional catalog note (present on a few entries)." } } } } }, "description": "Passthrough of the analytics service's pattern-descriptions response. The analytics envelope is nested, so the description catalog itself lives at data.data, keyed by pattern code." } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/analysis": { "get": { "operationId": "getPatternAnalysis", "tags": [ "Patterns" ], "summary": "Get the raw pattern analysis record", "description": "Returns the company's stored pattern analysis record from the intelligence results table \u2014 the raw analysis document underlying the recommendations. An agent should call this when it needs the full analysis detail (per-metric analyses, sample sizes, statistical metadata) rather than the ranked recommendation list. Returns an empty object when no analysis exists for the company yet.", "responses": { "200": { "description": "The stored analysis record, or an empty object if none exists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string", "description": "Tenant company ID (partition key)." }, "analysisKey": { "type": "string", "description": "Sort key identifying the record, e.g. tone_analysis, general_analysis, timing_matrix." }, "data": { "type": "object", "description": "The stored per-metric analysis document written by the intelligence pipeline (writeMetricAnalysis). Always a passthrough of the metric analyzer's full result; the exact keys under `analyses` vary per metric (e.g. days/am_pm for send timing, tone dimensions for tone analysis) and include chart-ready statistical detail.", "additionalProperties": true, "properties": { "analyses": { "type": "object", "additionalProperties": true, "description": "Per-dimension statistical analyses keyed by dimension name. Contents vary by metric and are produced by the intelligence analyzers (rates, sample sizes, significance flags, statsig detail)." }, "recommendations": { "type": "array", "items": { "type": "object", "description": "A recommendation record as generated by one metric analyzer (stored inside an analysis chunk, before company-level refinement/tiering). Same catalog-derived fields as PatternRecord but without companyId/updated stamps.", "additionalProperties": true, "properties": { "code": { "type": "string", "description": "Pattern code, e.g. TA-1, DOW-2." }, "title": { "type": "string", "description": "Display title (may contain HTML)." }, "message": { "type": "string", "description": "Recommendation text (may contain HTML)." }, "type": { "type": "string", "description": "Catalog record type, e.g. \"recommendation\"." }, "positive": { "type": "boolean" }, "tier": { "type": "number", "description": "Ranking tier; higher is stronger evidence." }, "evidence_tier": { "type": "string", "description": "Evidence tier label for estimation-layer leans (confirmed / likely / directional), when present." } } }, "description": "Recommendation records generated by this metric's analysis." }, "insights": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Insight records generated by this metric's analysis, when the analyzer emits them." }, "summary": { "type": "object", "additionalProperties": true, "description": "Aggregate engagement summary when the analyzer emits one (fields such as total_messages, total_opens, total_replies, total_meetings are summed by GET /patterns/contact-insights).", "properties": { "total_messages": { "type": "integer" }, "total_opens": { "type": "integer" }, "total_replies": { "type": "integer" }, "total_meetings": { "type": "integer" } } } } }, "metadata": { "type": "object", "description": "Metadata stamped on each stored analysis chunk by the intelligence writer.", "additionalProperties": true, "properties": { "metric": { "type": "string", "description": "Metric name (the analysisKey without the _analysis suffix)." }, "version": { "type": "string", "description": "Chunked-storage format version, currently \"2.0\"." }, "updated": { "type": "string", "description": "ISO 8601 timestamp of the last recompute." } } } }, "description": "The first stored analysis record for the company (rows are keyed companyId + analysisKey and returned in analysisKey order, so this is the lexicographically first record \u2014 usually a metric chunk, but possibly an operational row such as active_model_override). Empty object when no analysis has been generated. For a specific metric's analysis, prefer GET /patterns/chunks/{metricName}." } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/recipients": { "get": { "operationId": "getRecipientAnalysis", "tags": [ "Patterns" ], "summary": "Get recipient profile analysis", "description": "Returns the company's recipient-level analysis: how different audience segments and seniority positions respond to outreach. The payload is the UI-formatted summary produced by the intelligence pipeline, including an overview, segments, insights, and a position breakdown. An agent should call this to understand which recipient segments respond best before choosing targets or tailoring messaging. When no recipient data exists, a well-formed empty structure is returned (total_profiled 0, empty arrays).", "responses": { "200": { "description": "Recipient analysis summary (empty structure when no data).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "properties": { "overview": { "type": "object", "additionalProperties": true, "properties": { "total_profiled": { "type": "integer", "description": "Number of recipients profiled." }, "high_confidence_count": { "type": "integer", "description": "Recipients whose position inference is high-confidence." }, "segments_count": { "type": "integer", "description": "Number of audience segments." }, "last_updated": { "type": [ "string", "null" ], "description": "When the underlying summary was last recomputed." }, "has_sufficient_data": { "type": "boolean", "description": "Whether enough data exists for reliable segment conclusions." } } }, "segments": { "type": "array", "items": { "type": "object", "description": "One audience segment with response characteristics.", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Segment identifier." }, "name": { "type": "string", "description": "Display name, e.g. \"Technical Segment\"." }, "size": { "type": "integer", "description": "Number of recipients in the segment." }, "dominant_position": { "type": "string", "description": "Most common inferred position in the segment (\"unknown\" when mixed)." }, "key_insights": { "type": "array", "items": {}, "description": "Segment insight strings (or member samples in the lightweight profiler format)." }, "optimal_patterns": { "type": "object", "additionalProperties": true, "description": "Segment characteristics / optimal pattern data from the profiler." }, "confidence_level": { "type": "string", "enum": [ "high", "medium" ], "description": "high when segment size >= 10, else medium." } } } }, "insights": { "type": "array", "items": { "type": "object", "description": "One narrative insight about recipient behavior.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Insight type, e.g. position_pattern, segment_pattern, correlation, general." }, "title": { "type": "string", "description": "Generated user-friendly title." }, "description": { "type": "string", "description": "The insight text." }, "confidence": { "type": "string", "description": "Confidence label (defaults to \"medium\")." }, "icon": { "type": "string", "description": "PrimeNG icon class for UI rendering, e.g. pi-user." }, "actionable": { "type": "boolean", "description": "Always true in the current producer." }, "sample_size": { "type": "integer", "description": "Sample size behind the insight (0 when not tracked)." } } } }, "position_breakdown": { "type": "array", "items": { "type": "object", "description": "Aggregated per-position statistics (only positions with >= 3 profiled recipients, excluding \"unknown\"). Sorted by count descending.", "additionalProperties": true, "properties": { "position": { "type": "string", "description": "Inferred position bucket, e.g. c_suite, vp, manager, technical." }, "count": { "type": "integer", "description": "Profiled recipients in this position." }, "avg_confidence": { "type": "number", "description": "Average position-inference confidence (0-1, rounded to 2 decimals)." }, "total_responses": { "type": "integer", "description": "Total responses recorded from this position." }, "percentage": { "type": "number", "description": "Share of all profiled recipients, in percent (1 decimal)." } } } }, "validation": { "type": "object", "additionalProperties": true, "properties": { "has_significant_patterns": { "type": "boolean" }, "significant_dimensions": { "type": "array", "items": { "type": "string" }, "description": "Dimensions with statistically significant patterns (empty in the lightweight-profiler format)." }, "overall_confidence": { "type": "string", "enum": [ "high", "medium", "low" ] } } }, "charts": { "type": "object", "additionalProperties": true, "properties": { "position_distribution": { "type": "object", "description": "Chart.js-style chart configuration produced for UI rendering. An empty object when there is no data for the chart.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Chart type, e.g. doughnut, bar." }, "labels": { "type": "array", "items": { "type": "string" } }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "options": { "type": "object", "additionalProperties": true } } }, "confidence_levels": { "type": "object", "description": "Chart.js-style chart configuration produced for UI rendering. An empty object when there is no data for the chart.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Chart type, e.g. doughnut, bar." }, "labels": { "type": "array", "items": { "type": "string" } }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "options": { "type": "object", "additionalProperties": true } } }, "segment_sizes": { "type": "object", "description": "Chart.js-style chart configuration produced for UI rendering. An empty object when there is no data for the chart.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Chart type, e.g. doughnut, bar." }, "labels": { "type": "array", "items": { "type": "string" } }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "options": { "type": "object", "additionalProperties": true } } } }, "description": "Chart-ready data series for UI rendering (empty object per chart when no data)." } }, "description": "UI-formatted recipient analysis, produced by the intelligence pipeline's recipient profiler and stored on the recipient-summary \"main\" record. A well-formed empty structure (total_profiled 0, empty arrays) is returned when no data exists." } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/recommendation-profiles": { "get": { "operationId": "getRecommendationProfiles", "tags": [ "Patterns" ], "summary": "List recommendation-specific recipient profiles", "description": "Returns recipient profile records tied to specific recommendations \u2014 i.e., for a given recommendation code, which recipient profiles it applies to and how they responded. An agent should call this to drill into a single recommendation (using the recommendationCode filter) after fetching the ranked list from GET /patterns, for example to check which positions or segments a tone recommendation was validated against. Without the filter, all profile records for the company are returned.", "parameters": [ { "name": "recommendationCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to profiles whose recommendation_code matches this value (e.g. a pattern code such as \"TA-1\"). Omit to return all recommendation profiles for the company." } ], "responses": { "200": { "description": "Array of recommendation profile records (may be empty).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "array", "description": "Stored per-recipient profile rows for the company (hashed recipient IDs; only recipients with at least one recorded response). May be empty. See RecipientProfileRecord for the recommendationCode filter caveat.", "items": { "type": "object", "description": "One stored per-recipient profile row from the recipient-profiles table (written by the intelligence recipient profiler; only recipients with at least one response are stored). recipientId is a privacy-preserving 16-hex-char SHA-256 prefix of the email. Note: the current producer does not stamp a recommendation_code attribute on these rows, so the recommendationCode query filter only matches legacy rows that carry it.", "additionalProperties": true, "properties": { "companyId": { "type": "string", "description": "Tenant company ID (partition key)." }, "recipientId": { "type": "string", "description": "Hashed email identifier (sort key; first 16 hex chars of SHA-256)." }, "inferred_position": { "type": "string", "description": "Inferred position bucket (\"unknown\" when uncategorized)." }, "original_position": { "type": [ "string", "null" ], "description": "Original position text preserved when categorization fails; null/absent otherwise." }, "position_confidence": { "type": "number", "description": "Position-inference confidence, 0 to 1." }, "response_count": { "type": "integer", "description": "Responses recorded from this recipient (always >= 1 for stored rows)." }, "cluster_assignment": { "type": "integer", "description": "Cluster index from segmentation (-1 when unassigned)." }, "pattern_preferences": { "type": "object", "additionalProperties": true, "description": "Pattern-preference data from the profiler (shape owned by the intelligence pipeline)." }, "response_metrics": { "type": "object", "additionalProperties": true, "description": "Response-time pattern data. Present only on rows written by the single-profile path." }, "statistical_tests": { "type": "object", "additionalProperties": true, "description": "Per-recipient statistical test results. Present only on rows written by the single-profile path." }, "last_updated": { "type": "string", "description": "ISO 8601 timestamp of the last write." }, "email_domain": { "type": "string", "description": "Domain part of the recipient email (\"unknown\" when unavailable)." } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/chunks": { "get": { "operationId": "listPatternChunks", "tags": [ "Patterns" ], "summary": "List available analysis metric chunks", "description": "Returns the catalog of the eleven analysis metric \"chunks\" (tone, body content, subject lines, send timing, readability, personalization, social proof, messaging approach, key phrases, LLM analysis, recipient profiling), each annotated with whether data exists for this company, when it was last updated, and its record count and sample size. An agent should call this first to discover which analyses have data (hasData: true) before fetching individual chunks via GET /patterns/chunks/{metricName} \u2014 this avoids 404s on empty metrics.", "responses": { "200": { "description": "Chunk catalog with per-chunk availability and a summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "chunks": { "type": "array", "items": { "type": "object", "description": "Catalog entry for one analysis metric chunk.", "properties": { "name": { "type": "string", "description": "Metric name to use as the {metricName} path parameter." }, "displayName": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string", "description": "One of: communication, content, timing, strategy, advanced, audience." }, "analysisKey": { "type": "string" }, "hasData": { "type": "boolean", "description": "Whether stored analysis data exists for this chunk. Only fetch chunks with hasData true." }, "updated": { "type": [ "string", "null" ], "description": "When the chunk was last recomputed, or null if never." }, "recordCount": { "type": "integer", "description": "Number of recommendation records in the chunk." }, "sampleSize": { "type": "integer", "description": "Number of messages the chunk's analysis was computed over." } } } }, "summary": { "type": "object", "properties": { "totalChunks": { "type": "integer", "description": "Total metric chunks defined (11)." }, "chunksWithData": { "type": "integer", "description": "How many chunks have data for this company." }, "lastUpdated": { "type": [ "string", "null" ], "format": "date-time", "description": "Most recent update timestamp across chunks with data, or null." }, "totalRecords": { "type": "integer", "description": "Sum of recommendation record counts across chunks with data." } } }, "companyId": { "type": "string" } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/chunks/{metricName}": { "get": { "operationId": "getPatternChunk", "tags": [ "Patterns" ], "summary": "Get one analysis metric chunk", "description": "Returns the full stored analysis for a single metric chunk: its analysis document, recommendation records, insights, and quality metadata (sample size, significance level, data quality). An agent should call this after GET /patterns/chunks to pull the detailed data for a metric that has data \u2014 for example the send-timing chunk (general_analysis) before scheduling, or the tone chunk (tone_analysis) before drafting. Returns 404 if the metric name is not one of the known chunks or if no data exists for it.", "parameters": [ { "name": "metricName", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "tone_analysis", "body_analysis", "subject_analysis", "general_analysis", "ml_analysis", "personalization_analysis", "social_proof_analysis", "pain_aspirational_analysis", "text_analysis", "llm_analysis", "recipient_analysis_analysis" ] }, "description": "The metric chunk to fetch. One of the eleven known analysis keys; any other value returns 404." } ], "responses": { "200": { "description": "The requested chunk's analysis, recommendations, insights, and metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "metricName": { "type": "string" }, "displayName": { "type": "string", "description": "Human-readable metric name, e.g. \"Send Timing Optimization\"." }, "analysisKey": { "type": "string" }, "analysis": { "type": "object", "additionalProperties": true, "description": "The chunk's per-dimension analyses map (chunk data.analyses): statistical analyses keyed by dimension name (e.g. days, am_pm for send timing; tone dimensions for tone analysis). Contents vary by metric and include rates, sample sizes, and significance detail produced by the intelligence analyzers." }, "recommendations": { "type": "array", "items": { "type": "object", "description": "A recommendation record as generated by one metric analyzer (stored inside an analysis chunk, before company-level refinement/tiering). Same catalog-derived fields as PatternRecord but without companyId/updated stamps.", "additionalProperties": true, "properties": { "code": { "type": "string", "description": "Pattern code, e.g. TA-1, DOW-2." }, "title": { "type": "string", "description": "Display title (may contain HTML)." }, "message": { "type": "string", "description": "Recommendation text (may contain HTML)." }, "type": { "type": "string", "description": "Catalog record type, e.g. \"recommendation\"." }, "positive": { "type": "boolean" }, "tier": { "type": "number", "description": "Ranking tier; higher is stronger evidence." }, "evidence_tier": { "type": "string", "description": "Evidence tier label for estimation-layer leans (confirmed / likely / directional), when present." } } }, "description": "Recommendation records generated by this metric's analysis." }, "insights": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Insight records generated by this metric's analysis (empty for metrics whose analyzers do not emit insights)." }, "metadata": { "type": "object", "properties": { "version": { "type": "string", "description": "Analysis format version (defaults to \"2.0\")." }, "updated": { "type": [ "string", "null" ], "description": "When this chunk was last recomputed." }, "sampleSize": { "type": "integer", "description": "Number of messages the analysis was computed over." }, "significanceLevel": { "type": "number", "description": "Statistical significance level used (defaults to 0.95)." }, "recordCount": { "type": "integer", "description": "Number of recommendation records in this chunk." }, "dataQuality": { "type": "string", "description": "Data quality label (\"unknown\" when not set)." } } }, "companyId": { "type": "string" } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown metric name, or no chunk data exists for this metric.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/position-breakdown": { "get": { "operationId": "getPositionBreakdown", "tags": [ "Patterns" ], "summary": "Get per-position recommendation breakdown", "description": "Returns the position (seniority/role) breakdown of the company's recommendations, computed by the analytics service (this endpoint proxies an internal analytics Lambda that performs tone consolidation, sample-size-based confidence adjustment, and multi-company aggregation for agencies). An agent should call this to learn how each recommendation performs across recipient positions \u2014 e.g. which tones work for C-suite versus technical recipients \u2014 before tailoring outreach to a specific role.", "responses": { "200": { "description": "Position breakdown data grouped by recommendation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "description": "Position breakdown response. The populated payload is nested under `data` (the analytics service's response envelope is passed through whole); the outer breakdown_by_recommendation and summary fields currently always hold empty defaults.", "properties": { "data": { "type": "object", "description": "The analytics service's full position-breakdown payload. NOTE: because the public API wraps the analytics Lambda's entire response body, this whole payload appears under the outer `data.data` key; the sibling breakdown_by_recommendation and summary at the outer level are envelope artifacts that currently always hold empty defaults \u2014 read the populated values from inside this object.", "additionalProperties": true, "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One consolidated per-position row produced by the analytics position-breakdown transformation (grouping every recommendation's data for that position). Rows are sorted by total_responses descending.", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "analysis_type": { "type": "string", "description": "position_consolidated_{position}." }, "analysisKey": { "type": "string", "description": "position_profile_{position}." }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "properties": { "position": { "type": "string", "description": "Position bucket name." }, "total_responses": { "type": "integer", "description": "Highest per-recommendation response count for this position." }, "unique_recipients": { "type": "integer" }, "recommendation_count": { "type": "integer" }, "recommendations": { "type": "array", "items": { "type": "object", "description": "One recommendation's contribution to a consolidated position row.", "additionalProperties": true, "properties": { "recommendation_code": { "type": "string", "description": "Base code with any numeric suffix stripped, e.g. TA." }, "full_recommendation_code": { "type": "string", "description": "Full code, e.g. TA-1." }, "metric": { "type": "string", "description": "Metric/strategy string (defaults to \"recommendation\")." }, "response_count": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence": { "type": "object", "additionalProperties": true, "description": "The per-position confidence object for this recommendation (see PositionConfidence)." }, "communication_preferences": { "type": "object", "additionalProperties": true, "description": "The per-position communication preferences for this recommendation (see PositionCommunicationPreferences)." } } }, "description": "Contributing recommendations, sorted by response count descending." }, "consolidated_communication_preferences": { "type": "object", "description": "Communication preferences consolidated across all recommendations for one position (most-common values win; word count / readability averaged).", "additionalProperties": true, "properties": { "best_day_of_week": { "type": "string", "description": "\"Unknown\" when no data." }, "best_time_of_day": { "type": "string", "description": "\"Unknown\" when no data." }, "best_time_range": { "type": "string", "description": "\"Unknown\" when no data." }, "optimal_word_count": { "type": "integer", "description": "Average optimal word count (0 when unknown)." }, "optimal_readability": { "type": "integer", "description": "Average optimal readability (0 when unknown)." }, "dominant_tones": { "type": "array", "items": { "type": "string" }, "description": "Up to 3 distinct dominant tones." }, "tone_combination": { "type": "string", "description": "Best-performing tone or tone combination parsed from the top tone recommendation, e.g. \"professional + urgent\" (\"Unknown\" when unparseable)." }, "tone_source": { "type": "string", "enum": [ "recommendation", "aggregated" ], "description": "Whether the tone came from a tone recommendation or aggregated message data." }, "tone_recommendation_meta": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Performance metadata of the tone recommendation the tone was taken from; null when tone came from aggregation.", "properties": { "recommendation_code": { "type": "string" }, "response_count": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence": { "type": "object", "additionalProperties": true }, "metric": { "type": "string", "description": "Metric string with emojis stripped." } } } } }, "confidence": { "type": "object", "description": "Aggregate confidence for one position row, averaged across its recommendations and capped by sample-size penalties (<30 responses caps at Medium, <15 at Low, <10 forces Very Low).", "additionalProperties": true, "properties": { "score": { "type": "integer", "description": "Adjusted confidence score, 0-100." }, "level": { "type": "string", "description": "Adjusted level: Very Low, Low, Medium, High, or Very High." }, "display_text": { "type": "string", "description": "Same as level." }, "based_on_recommendations": { "type": "integer", "description": "Number of recommendations aggregated." }, "sample_size": { "type": "integer", "description": "Highest per-recommendation response count for this position (not a sum, to avoid double-counting)." }, "unique_recipients": { "type": "integer" }, "quality_rating": { "type": "string", "enum": [ "EXCELLENT", "GOOD", "FAIR", "POOR" ] }, "sample_size_limited": { "type": "boolean", "description": "True when fewer than 30 responses forced a confidence downgrade." }, "original_level": { "type": "string", "description": "Most common per-recommendation level before the sample-size penalty." } } }, "sourceCompanies": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "companyType": { "type": "string" }, "responseCount": { "type": "integer" }, "recommendationCount": { "type": "integer" }, "confidence": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Per-company aggregated confidence with the same sample-size penalties; null when no scores were available." } } }, "description": "Present only in agency (multi-company) views: per-company contribution to this position row, sorted by responseCount descending." } } }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "position": { "type": "string" }, "recommendation_count": { "type": "integer" }, "total_responses": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence_level": { "type": "string", "description": "Most common level before the sample-size penalty." } } }, "ui_data": { "type": "object", "additionalProperties": true, "description": "Compact UI projection of the same row.", "properties": { "position": { "type": "string" }, "total_responses": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "recommendations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": "string" }, "full_code": { "type": "string" }, "metric": { "type": "string" }, "response_count": { "type": "integer" } } } }, "communication_preferences": { "type": "object", "description": "Communication preferences consolidated across all recommendations for one position (most-common values win; word count / readability averaged).", "additionalProperties": true, "properties": { "best_day_of_week": { "type": "string", "description": "\"Unknown\" when no data." }, "best_time_of_day": { "type": "string", "description": "\"Unknown\" when no data." }, "best_time_range": { "type": "string", "description": "\"Unknown\" when no data." }, "optimal_word_count": { "type": "integer", "description": "Average optimal word count (0 when unknown)." }, "optimal_readability": { "type": "integer", "description": "Average optimal readability (0 when unknown)." }, "dominant_tones": { "type": "array", "items": { "type": "string" }, "description": "Up to 3 distinct dominant tones." }, "tone_combination": { "type": "string", "description": "Best-performing tone or tone combination parsed from the top tone recommendation, e.g. \"professional + urgent\" (\"Unknown\" when unparseable)." }, "tone_source": { "type": "string", "enum": [ "recommendation", "aggregated" ], "description": "Whether the tone came from a tone recommendation or aggregated message data." }, "tone_recommendation_meta": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Performance metadata of the tone recommendation the tone was taken from; null when tone came from aggregation.", "properties": { "recommendation_code": { "type": "string" }, "response_count": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence": { "type": "object", "additionalProperties": true }, "metric": { "type": "string", "description": "Metric string with emojis stripped." } } } } }, "confidence": { "type": "string", "description": "Most common confidence level label." } } } } }, "description": "Consolidated per-position rows, sorted by total_responses descending." }, "breakdown_by_recommendation": { "type": "object", "description": "Position profiles keyed by recommendation code (e.g. TA-1, DOW-2).", "additionalProperties": { "type": "object", "description": "Position breakdown for one recommendation code, as stored on recipient-summary recommendation_position_breakdown_{code} rows by the intelligence pipeline (and merged across companies for agency views by the analytics service).", "additionalProperties": true, "properties": { "recommendation_code": { "type": "string", "description": "The recommendation code this profile belongs to, e.g. TA-1." }, "metric": { "type": "string", "description": "Human-readable metric/strategy string for the recommendation (may embed a response-rate summary)." }, "total_responses": { "type": "integer", "description": "Responding messages matched to this recommendation's pattern." }, "position_breakdown": { "type": "object", "description": "Per-position statistics keyed by position bucket (e.g. c_suite, vp, manager, technical, unknown).", "additionalProperties": { "type": "object", "description": "Per-position statistics for one recommendation, produced by the intelligence recommendation recipient profiler.", "additionalProperties": true, "properties": { "response_count": { "type": "integer", "description": "Responding messages attributed to this position for the recommendation." }, "unique_recipients": { "type": "integer", "description": "Distinct recipients behind those responses." }, "response_rate_for_position": { "type": [ "number", "null" ], "description": "P(response | position) = responders / messages sent to this position over the full message set, rounded to 4 decimals. Null when the denominator is unavailable (never fabricated)." }, "communication_preferences": { "type": "object", "description": "Optimal communication preferences computed for one position from its responding messages.", "additionalProperties": true, "properties": { "optimal_word_count": { "type": "integer", "description": "Mean word count of responding messages (0 when unknown)." }, "optimal_readability": { "type": "number", "description": "Mean readability score (0 when unknown)." }, "best_time_of_day": { "type": "string", "description": "Formatted mean send time, e.g. \"3:16 PM\" (\"Unknown\" when no data)." }, "best_time_range": { "type": "string", "description": "Concentrated send-time window, e.g. \"1pm-6pm (afternoon)\" (\"Unknown\" when insufficient data)." }, "best_day_of_week": { "type": "string", "description": "Most common response day (\"Unknown\" when no data)." }, "dominant_tones": { "type": "array", "items": { "type": "string" }, "description": "Top 3 most common tones in responding messages." }, "tone_combination": { "type": "string", "description": "Most common two-tone combination, e.g. \"professional + questioning\" (\"Unknown\" when none)." }, "tone_confidence": { "type": "number", "description": "0-1 consistency score of the top tone across messages." } } }, "confidence": { "type": "object", "description": "Detailed statistical confidence for one position's breakdown, computed by the intelligence profiler against per-position sent/responded denominators over the full message set.", "additionalProperties": true, "properties": { "level": { "type": "string", "description": "Confidence level label: Very Low, Low, Medium, High, or Very High." }, "score": { "type": "number", "description": "Composite confidence score, 0-100." }, "max_score": { "type": "number", "description": "Maximum composite score (100)." }, "summary": { "type": "string", "description": "One-line reasoning summary." }, "factors": { "type": "object", "additionalProperties": true, "description": "Per-factor score contributions.", "properties": { "sample_size": { "type": "number" }, "response_consistency": { "type": "number" }, "pattern_strength": { "type": "number" }, "statistical_significance": { "type": "number" } } }, "explanations": { "type": "array", "items": { "type": "string" }, "description": "Human-readable factor explanations." }, "recommendations": { "type": "array", "items": { "type": "string" }, "description": "Actionable guidance based on the confidence level." }, "confidence_level": { "type": "number", "description": "Statistical confidence level of the interval (e.g. 0.95)." }, "margin_of_error": { "type": "number", "description": "Margin of error of the response-rate estimate (fraction)." }, "lower_bound": { "type": "number", "description": "Lower bound of the response-rate confidence interval." }, "upper_bound": { "type": "number", "description": "Upper bound of the response-rate confidence interval." }, "sample_size": { "type": "integer", "description": "Messages sent to this position (the denominator n)." }, "position_responses": { "type": "integer", "description": "Responses from this position (the numerator x)." }, "campaign_count": { "type": "integer", "description": "Distinct campaigns contributing messages." }, "effective_sample_size": { "type": "number", "description": "Clustering-adjusted effective sample size." }, "design_effect": { "type": "number", "description": "Design effect from campaign clustering." }, "quality_rating": { "type": "string", "description": "Quality label: EXCELLENT, GOOD, FAIR, or POOR." }, "display_text": { "type": "string", "description": "Pre-formatted confidence sentence for display." }, "adequate_sample": { "type": "boolean", "description": "Whether the sample passes the normal-approximation adequacy gate. False means the numbers are suggestive, not statistically validated." } } }, "original_position_texts": { "type": "array", "items": { "type": "string" }, "description": "Original position strings that resolved to \"unknown\". Present only on the unknown bucket." } } } }, "consolidated_messaging_guide": { "type": "object", "additionalProperties": true, "description": "Unified messaging guide consolidated across the validated positions (timing, word count, tone guidance and a confidence_level). Shape owned by the intelligence profiler." } } } }, "summary": { "type": "object", "additionalProperties": true, "properties": { "total_recommendations": { "type": "integer", "description": "Recommendation codes with stored position profiles." }, "total_position_entries": { "type": "integer", "description": "Consolidated position rows produced." }, "recommendations_with_data": { "type": "integer", "description": "Recommendations whose position_breakdown is non-empty." } } }, "generated_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string" }, "perCompanySummary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "companyType": { "type": "string" }, "hasData": { "type": "boolean" }, "recommendationCount": { "type": "integer" } } }, "description": "Present only in agency (multi-company) views: per-company data availability." } } }, "breakdown_by_recommendation": { "type": "object", "additionalProperties": { "type": "object", "description": "Position breakdown for one recommendation code, as stored on recipient-summary recommendation_position_breakdown_{code} rows by the intelligence pipeline (and merged across companies for agency views by the analytics service).", "additionalProperties": true, "properties": { "recommendation_code": { "type": "string", "description": "The recommendation code this profile belongs to, e.g. TA-1." }, "metric": { "type": "string", "description": "Human-readable metric/strategy string for the recommendation (may embed a response-rate summary)." }, "total_responses": { "type": "integer", "description": "Responding messages matched to this recommendation's pattern." }, "position_breakdown": { "type": "object", "description": "Per-position statistics keyed by position bucket (e.g. c_suite, vp, manager, technical, unknown).", "additionalProperties": { "type": "object", "description": "Per-position statistics for one recommendation, produced by the intelligence recommendation recipient profiler.", "additionalProperties": true, "properties": { "response_count": { "type": "integer", "description": "Responding messages attributed to this position for the recommendation." }, "unique_recipients": { "type": "integer", "description": "Distinct recipients behind those responses." }, "response_rate_for_position": { "type": [ "number", "null" ], "description": "P(response | position) = responders / messages sent to this position over the full message set, rounded to 4 decimals. Null when the denominator is unavailable (never fabricated)." }, "communication_preferences": { "type": "object", "description": "Optimal communication preferences computed for one position from its responding messages.", "additionalProperties": true, "properties": { "optimal_word_count": { "type": "integer", "description": "Mean word count of responding messages (0 when unknown)." }, "optimal_readability": { "type": "number", "description": "Mean readability score (0 when unknown)." }, "best_time_of_day": { "type": "string", "description": "Formatted mean send time, e.g. \"3:16 PM\" (\"Unknown\" when no data)." }, "best_time_range": { "type": "string", "description": "Concentrated send-time window, e.g. \"1pm-6pm (afternoon)\" (\"Unknown\" when insufficient data)." }, "best_day_of_week": { "type": "string", "description": "Most common response day (\"Unknown\" when no data)." }, "dominant_tones": { "type": "array", "items": { "type": "string" }, "description": "Top 3 most common tones in responding messages." }, "tone_combination": { "type": "string", "description": "Most common two-tone combination, e.g. \"professional + questioning\" (\"Unknown\" when none)." }, "tone_confidence": { "type": "number", "description": "0-1 consistency score of the top tone across messages." } } }, "confidence": { "type": "object", "description": "Detailed statistical confidence for one position's breakdown, computed by the intelligence profiler against per-position sent/responded denominators over the full message set.", "additionalProperties": true, "properties": { "level": { "type": "string", "description": "Confidence level label: Very Low, Low, Medium, High, or Very High." }, "score": { "type": "number", "description": "Composite confidence score, 0-100." }, "max_score": { "type": "number", "description": "Maximum composite score (100)." }, "summary": { "type": "string", "description": "One-line reasoning summary." }, "factors": { "type": "object", "additionalProperties": true, "description": "Per-factor score contributions.", "properties": { "sample_size": { "type": "number" }, "response_consistency": { "type": "number" }, "pattern_strength": { "type": "number" }, "statistical_significance": { "type": "number" } } }, "explanations": { "type": "array", "items": { "type": "string" }, "description": "Human-readable factor explanations." }, "recommendations": { "type": "array", "items": { "type": "string" }, "description": "Actionable guidance based on the confidence level." }, "confidence_level": { "type": "number", "description": "Statistical confidence level of the interval (e.g. 0.95)." }, "margin_of_error": { "type": "number", "description": "Margin of error of the response-rate estimate (fraction)." }, "lower_bound": { "type": "number", "description": "Lower bound of the response-rate confidence interval." }, "upper_bound": { "type": "number", "description": "Upper bound of the response-rate confidence interval." }, "sample_size": { "type": "integer", "description": "Messages sent to this position (the denominator n)." }, "position_responses": { "type": "integer", "description": "Responses from this position (the numerator x)." }, "campaign_count": { "type": "integer", "description": "Distinct campaigns contributing messages." }, "effective_sample_size": { "type": "number", "description": "Clustering-adjusted effective sample size." }, "design_effect": { "type": "number", "description": "Design effect from campaign clustering." }, "quality_rating": { "type": "string", "description": "Quality label: EXCELLENT, GOOD, FAIR, or POOR." }, "display_text": { "type": "string", "description": "Pre-formatted confidence sentence for display." }, "adequate_sample": { "type": "boolean", "description": "Whether the sample passes the normal-approximation adequacy gate. False means the numbers are suggestive, not statistically validated." } } }, "original_position_texts": { "type": "array", "items": { "type": "string" }, "description": "Original position strings that resolved to \"unknown\". Present only on the unknown bucket." } } } }, "consolidated_messaging_guide": { "type": "object", "additionalProperties": true, "description": "Unified messaging guide consolidated across the validated positions (timing, word count, tone guidance and a confidence_level). Shape owned by the intelligence profiler." } } }, "description": "Envelope artifact: currently always an empty object. The populated per-recommendation map is at data.breakdown_by_recommendation." }, "summary": { "type": "object", "additionalProperties": true, "properties": { "total_recommendations": { "type": "integer", "description": "Recommendation codes with stored position profiles." }, "total_position_entries": { "type": "integer", "description": "Consolidated position rows produced." }, "recommendations_with_data": { "type": "integer", "description": "Recommendations whose position_breakdown is non-empty." } }, "description": "Envelope artifact: currently always the zero-valued default. The populated summary is at data.summary." }, "generated_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string" } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/patterns/contact-insights": { "get": { "operationId": "getContactInsights", "tags": [ "Patterns" ], "summary": "Get pattern insights tailored to one contact", "description": "Returns a contact-oriented insight bundle: the company's top patterns (cleaned for display), an aggregate engagement summary, and position-specific messaging recommendations inferred from the contact's job title. When a position is supplied, the service infers a position category (executive, management, technical, marketing, sales, finance, support) and matches it against the company's position breakdown data, falling back to sensible category defaults when no matching data exists. An agent should call this when preparing outreach to a specific person \u2014 pass the contact's title as `position` to get role-tailored guidance. When the company has no pattern data at all, hasData is false and a noDataOptions block describes UI actions for gathering input.", "parameters": [ { "name": "contactId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CRM contact identifier. Echoed back in the response; not required for insight computation." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Contact email address. Accepted and logged for context; not currently used to filter results." }, { "name": "position", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The contact's job title or position (free text, e.g. \"VP of Engineering\"). Used to infer a position category and select position-specific recommendations. When omitted or unmatched, general/unknown-category recommendations are returned." } ], "responses": { "200": { "description": "Contact-tailored insight bundle.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "engagementSummary": { "type": "object", "properties": { "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "replies": { "type": "integer" }, "meetings": { "type": "integer" } }, "description": "Aggregate engagement totals summed across the company's analysis chunks." }, "patterns": { "type": "array", "items": { "type": "object", "properties": { "patternCode": { "type": [ "string", "null" ], "description": "Pattern code (e.g. TA-1, DOW-2)." }, "name": { "type": "string", "description": "Display name, HTML-stripped." }, "description": { "type": "string", "description": "Pattern description, HTML-stripped." }, "recommendation": { "type": "string", "description": "Recommended action text, HTML-stripped." }, "lift": { "type": "number", "description": "Observed lift for this pattern (0 when unknown)." }, "tier": { "type": "number", "description": "Pattern tier / strength ranking (0 when unknown)." }, "confidence": { "type": "string", "description": "Confidence label (defaults to \"MODERATE\")." } } } }, "positionInsights": { "type": "object", "properties": { "position": { "type": "string", "description": "Inferred position category, or \"unknown\"." }, "originalPosition": { "type": "string", "description": "The position string supplied by the caller (empty when omitted)." }, "confidence": { "type": "number", "description": "Position inference confidence, 0 to 1 (0 when no position supplied or unmatched)." }, "matchedBreakdown": { "type": "string", "description": "The position-breakdown key the category was matched to. Present only when real breakdown data was found." }, "recommendations": { "type": "array", "items": { "type": "string" }, "description": "Plain-text messaging recommendations for this position (data-derived when available, otherwise category defaults)." } } }, "lastUpdated": { "type": "string", "format": "date-time" }, "companyId": { "type": "string" }, "contactId": { "type": [ "string", "null" ], "description": "Echo of the contactId query parameter." }, "hasData": { "type": "boolean", "description": "False when the company has no pattern data yet." }, "noDataOptions": { "type": "object", "additionalProperties": true, "description": "Present only when hasData is false. Describes UI options (sequence selector, email input) for gathering data, with a message and an actions array." } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/intelligence/contact-history": { "get": { "operationId": "getContactHistory", "tags": [ "Intelligence" ], "summary": "Get AG decision history for a contact", "description": "Returns the most recent Anchored Growth workflow-intelligence decisions recorded for a specific contact, newest first: which channel and tone were recommended, at what confidence, the suggested send day/hour and word count, the recorded outcome (if any), and Thompson-sampling context such as exploration flags, alternative recommendations, and selection margins. An agent should call this before re-engaging a contact to see what was already recommended and how it turned out, avoiding repeated or contradictory outreach. Requires the contactEmail query parameter; returns 400 without it.", "parameters": [ { "name": "contactEmail", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The contact's email address. Decisions are looked up by (company, contact email)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 25, "minimum": 1 }, "description": "Maximum number of decisions to return. Defaults to 10; values above 25 are clamped to 25." } ], "responses": { "200": { "description": "Decision history for the contact, newest first (empty when none recorded).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message", "data", "timestamp" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "contactEmail": { "type": "string" }, "decisions": { "type": "array", "items": { "type": "object", "description": "One recorded workflow-intelligence decision for a contact. Null-valued fields mean the decision predates that field or the data was not captured.", "properties": { "timestamp": { "type": [ "string", "null" ], "description": "When the decision was made." }, "channel": { "type": [ "string", "null" ], "description": "Recommended outreach channel (e.g. email, linkedin)." }, "confidence": { "type": [ "number", "null" ], "description": "Confidence score for the recommendation." }, "tone": { "type": [ "string", "null" ], "description": "Recommended message tone." }, "bestDay": { "type": [ "string", "null" ], "description": "Recommended send day." }, "bestHour": { "type": [ "string", "null" ], "description": "Recommended send hour." }, "position": { "type": [ "string", "null" ], "description": "Position profile the recommendation was based on." }, "wordCount": { "type": [ "string", "null" ], "description": "Recommended message word count." }, "outcome": { "type": [ "string", "null" ], "description": "Recorded outcome type for this decision, if an outcome was reported." }, "outcomeTimestamp": { "type": [ "string", "null" ], "description": "When the outcome was recorded." }, "dataSource": { "type": [ "string", "null" ], "description": "Data-quality/source label for the decision." }, "isExploration": { "type": "boolean", "description": "True when the bandit chose this arm for exploration rather than exploitation." }, "automationDecision": { "type": [ "string", "null" ], "description": "The automation decision issued (e.g. send / hold)." }, "channelAlternatives": { "type": [ "array", "null" ], "items": {}, "description": "Alternative channel recommendations considered, when recorded." }, "toneAlternatives": { "type": [ "array", "null" ], "items": {}, "description": "Alternative tone recommendations considered, when recorded." }, "channelMargin": { "type": [ "number", "null" ], "description": "Margin by which the chosen channel beat the runner-up." }, "toneMargin": { "type": [ "number", "null" ], "description": "Margin by which the chosen tone beat the runner-up." }, "channelSelectionMode": { "type": [ "string", "null" ], "description": "\"comparative\" when a real Thompson comparison was made, \"single_channel\" when only one channel was active, null for legacy decisions predating this field." } } } }, "total": { "type": "integer", "description": "Number of decisions returned in this response." } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "400": { "description": "Missing required contactEmail query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } } }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Self-serve `ag_` API key sent as `Authorization: Bearer ag_...`. Mint and manage keys at https://app.anchoredgrowth.io/mcp-access. The key itself identifies your company \u2014 no other identifier is needed. Never send ag_ keys in the query string; the API rejects that with 401." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative to bearer auth: the same `ag_` self-serve key sent in the X-API-Key header." } }, "responses": { "Unauthorized": { "description": "Authentication failed: missing, invalid, revoked, or expired API key, or an ag_ key sent via query string. The body includes a machine-readable `reason` code such as TOKEN_NOT_FOUND, TOKEN_INACTIVE, TOKEN_EXPIRED, TOKEN_LOCKED, INVALID_FORMAT, or SELF_SERVE_KEY_IN_QUERY_STRING.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key authenticated but lacks the required permission (analytics_read). The body includes `requiredPermission` and the key's `userPermissions`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Request rejected for one of three throttles: burst rate limit exceeded (reason BURST_RATE_LIMITED; default 200 requests per 15-minute window per key), monthly quota exhausted (reason QUOTA_EXCEEDED; body includes quotaLimit, currentUsage, resetAt), or too many failed authentication attempts from this source (reason TOO_MANY_FAILED_ATTEMPTS). Burst-limit responses include X-Rate-Limit-* and Retry-After headers.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on burst-limit and failed-attempt throttles).", "schema": { "type": "integer" } }, "X-Rate-Limit-Limit": { "description": "The rate limit ceiling for the current window (burst-limit responses).", "schema": { "type": "integer" } }, "X-Rate-Limit-Remaining": { "description": "Requests remaining in the current window (burst-limit responses).", "schema": { "type": "integer" } }, "X-Rate-Limit-Reset": { "description": "When the current window resets (burst-limit responses).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Unexpected server-side failure while handling the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "schemas": { "Error": { "type": "object", "description": "Authentication / authorization / throttling error body (returned by the auth middleware for 401, 403, and 429). Always carries `error` and `message`. Depending on the failure it may also carry: `reason` (machine-readable code), `requiredPermission` and `userPermissions` (403), `retryAfter`, `quotaLimit`, `currentUsage`, `resetAt` (429), and `securityNote`.", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Short error category, e.g. \"Authentication failed\", \"Insufficient permissions\", \"Rate limit exceeded\", \"Quota exceeded\"." }, "message": { "type": "string", "description": "Human-readable explanation of the failure." }, "reason": { "type": "string", "description": "Machine-readable reason code (e.g. TOKEN_EXPIRED, QUOTA_EXCEEDED, BURST_RATE_LIMITED). Not present on all variants." } }, "additionalProperties": true }, "ApiError": { "type": "object", "description": "Handler-level error envelope (400, 404, 500) produced by the shared error helper: success is false, `error` is a machine-readable code (e.g. missing_parameter, not_found, internal_error), and `message` explains the failure. A `details` object may be present outside production.", "required": [ "success", "error", "message", "timestamp" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "Machine-readable error code: invalid_request, missing_parameter, not_found, internal_error, or service_error." }, "message": { "type": "string", "description": "Human-readable explanation." }, "timestamp": { "type": "string", "format": "date-time" }, "details": { "type": "object", "additionalProperties": true, "description": "Additional error context (included outside production, and always for validation and rate_limit error types)." } }, "additionalProperties": true }, "PatternRecord": { "type": "object", "description": "A stored pattern recommendation record from the intelligence pipeline's ai-recommendations table (written by the intelligence service's writeRecommendations). Base fields come from the recommendation catalog (code, title, type, message, positive, tier) with template values substituted; the writer stamps companyId and updated. Metric analyzers may attach extra fields (e.g. evidence_tier, metric, description); fallback observation records (codes ending in -OBS-*) omit type. The message/title strings may contain HTML markup.", "additionalProperties": true, "required": [ "companyId", "code" ], "properties": { "companyId": { "type": "string", "description": "Tenant company ID (table partition key)." }, "code": { "type": "string", "description": "Pattern code and table sort key, e.g. TA-1, DOW-2, BWC-OBS-1." }, "title": { "type": "string", "description": "Display title (template-substituted; may contain HTML)." }, "message": { "type": "string", "description": "Recommendation text (template-substituted; may contain HTML)." }, "type": { "type": "string", "description": "Catalog record type, e.g. \"recommendation\". Absent on fallback observation records." }, "positive": { "type": "boolean", "description": "Whether the pattern is a positive (do-more-of-this) recommendation." }, "tier": { "type": "number", "description": "Ranking tier; higher tiers indicate stronger evidence. Results are sorted by tier descending." }, "updated": { "type": "string", "description": "ISO 8601 timestamp stamped when the record was last written." }, "evidence_tier": { "type": "string", "description": "Evidence tier label attached by the estimation layer for lean-style recommendations (e.g. confirmed, likely, directional). Present only on records that carry it." }, "metric": { "type": "string", "description": "Human-readable metric/strategy string attached by some analyzers (e.g. tone strategy summaries). Present only on records that carry it." } } }, "ChunkListing": { "type": "object", "description": "Catalog entry for one analysis metric chunk.", "properties": { "name": { "type": "string", "description": "Metric name to use as the {metricName} path parameter." }, "displayName": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string", "description": "One of: communication, content, timing, strategy, advanced, audience." }, "analysisKey": { "type": "string" }, "hasData": { "type": "boolean", "description": "Whether stored analysis data exists for this chunk. Only fetch chunks with hasData true." }, "updated": { "type": [ "string", "null" ], "description": "When the chunk was last recomputed, or null if never." }, "recordCount": { "type": "integer", "description": "Number of recommendation records in the chunk." }, "sampleSize": { "type": "integer", "description": "Number of messages the chunk's analysis was computed over." } } }, "ContactDecision": { "type": "object", "description": "One recorded workflow-intelligence decision for a contact. Null-valued fields mean the decision predates that field or the data was not captured.", "properties": { "timestamp": { "type": [ "string", "null" ], "description": "When the decision was made." }, "channel": { "type": [ "string", "null" ], "description": "Recommended outreach channel (e.g. email, linkedin)." }, "confidence": { "type": [ "number", "null" ], "description": "Confidence score for the recommendation." }, "tone": { "type": [ "string", "null" ], "description": "Recommended message tone." }, "bestDay": { "type": [ "string", "null" ], "description": "Recommended send day." }, "bestHour": { "type": [ "string", "null" ], "description": "Recommended send hour." }, "position": { "type": [ "string", "null" ], "description": "Position profile the recommendation was based on." }, "wordCount": { "type": [ "string", "null" ], "description": "Recommended message word count." }, "outcome": { "type": [ "string", "null" ], "description": "Recorded outcome type for this decision, if an outcome was reported." }, "outcomeTimestamp": { "type": [ "string", "null" ], "description": "When the outcome was recorded." }, "dataSource": { "type": [ "string", "null" ], "description": "Data-quality/source label for the decision." }, "isExploration": { "type": "boolean", "description": "True when the bandit chose this arm for exploration rather than exploitation." }, "automationDecision": { "type": [ "string", "null" ], "description": "The automation decision issued (e.g. send / hold)." }, "channelAlternatives": { "type": [ "array", "null" ], "items": {}, "description": "Alternative channel recommendations considered, when recorded." }, "toneAlternatives": { "type": [ "array", "null" ], "items": {}, "description": "Alternative tone recommendations considered, when recorded." }, "channelMargin": { "type": [ "number", "null" ], "description": "Margin by which the chosen channel beat the runner-up." }, "toneMargin": { "type": [ "number", "null" ], "description": "Margin by which the chosen tone beat the runner-up." }, "channelSelectionMode": { "type": [ "string", "null" ], "description": "\"comparative\" when a real Thompson comparison was made, \"single_channel\" when only one channel was active, null for legacy decisions predating this field." } } }, "PatternDescriptionEntry": { "type": "object", "description": "Narrative description of one pattern code, from the analytics service's static descriptions catalog (descriptions.json).", "additionalProperties": true, "required": [ "description", "category", "analysis", "type" ], "properties": { "description": { "type": "array", "items": { "type": "string" }, "description": "Ordered paragraphs explaining when the recommendation fires and how to act on it." }, "category": { "type": "array", "items": { "type": "string" }, "description": "Category path, e.g. [\"general\", \"day_of_week\"]." }, "analysis": { "type": "array", "items": { "type": "string" }, "description": "Which analysis series the pattern is derived from, e.g. [\"days\"], [\"hourly\"]." }, "type": { "type": "string", "description": "Chart/dimension type for the pattern, e.g. day, hour, range, tone." }, "chartType": { "type": "string", "description": "Preferred chart rendering (present on tone codes only), e.g. \"bar\"." }, "note": { "type": "string", "description": "Additional catalog note (present on a few entries)." } } }, "PatternDescriptionsEnvelope": { "type": "object", "description": "Passthrough of the analytics service's own response envelope (the public API wraps the analytics Lambda's full response body, so the analytics-level success flag and data appear nested here).", "additionalProperties": true, "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true, "description": "Analytics-service envelope flag (always true on a 200)." }, "data": { "type": "object", "description": "Map of pattern code (e.g. DOW-2, TA-1, BWC-1) to its description entry. 51 codes in the current catalog.", "additionalProperties": { "$ref": "#/components/schemas/PatternDescriptionEntry" } } } }, "MetricRecommendation": { "type": "object", "description": "A recommendation record as generated by one metric analyzer (stored inside an analysis chunk, before company-level refinement/tiering). Same catalog-derived fields as PatternRecord but without companyId/updated stamps.", "additionalProperties": true, "properties": { "code": { "type": "string", "description": "Pattern code, e.g. TA-1, DOW-2." }, "title": { "type": "string", "description": "Display title (may contain HTML)." }, "message": { "type": "string", "description": "Recommendation text (may contain HTML)." }, "type": { "type": "string", "description": "Catalog record type, e.g. \"recommendation\"." }, "positive": { "type": "boolean" }, "tier": { "type": "number", "description": "Ranking tier; higher is stronger evidence." }, "evidence_tier": { "type": "string", "description": "Evidence tier label for estimation-layer leans (confirmed / likely / directional), when present." } } }, "MetricAnalysisData": { "type": "object", "description": "The stored per-metric analysis document written by the intelligence pipeline (writeMetricAnalysis). Always a passthrough of the metric analyzer's full result; the exact keys under `analyses` vary per metric (e.g. days/am_pm for send timing, tone dimensions for tone analysis) and include chart-ready statistical detail.", "additionalProperties": true, "properties": { "analyses": { "type": "object", "additionalProperties": true, "description": "Per-dimension statistical analyses keyed by dimension name. Contents vary by metric and are produced by the intelligence analyzers (rates, sample sizes, significance flags, statsig detail)." }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/MetricRecommendation" }, "description": "Recommendation records generated by this metric's analysis." }, "insights": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Insight records generated by this metric's analysis, when the analyzer emits them." }, "summary": { "type": "object", "additionalProperties": true, "description": "Aggregate engagement summary when the analyzer emits one (fields such as total_messages, total_opens, total_replies, total_meetings are summed by GET /patterns/contact-insights).", "properties": { "total_messages": { "type": "integer" }, "total_opens": { "type": "integer" }, "total_replies": { "type": "integer" }, "total_meetings": { "type": "integer" } } } } }, "AnalysisChunkMetadata": { "type": "object", "description": "Metadata stamped on each stored analysis chunk by the intelligence writer.", "additionalProperties": true, "properties": { "metric": { "type": "string", "description": "Metric name (the analysisKey without the _analysis suffix)." }, "version": { "type": "string", "description": "Chunked-storage format version, currently \"2.0\"." }, "updated": { "type": "string", "description": "ISO 8601 timestamp of the last recompute." } } }, "AnalysisRecord": { "type": "object", "description": "One stored row of the intelligence results (ai-results) table. Most rows are metric analysis chunks (analysisKey = \"{metric}_analysis\"); the table also holds operational rows written by the same pipeline (e.g. active_model_override, timing_matrix, confidence_calibration, channel_effectiveness) whose `data` follows that subsystem's own shape \u2014 hence the open leaf objects.", "additionalProperties": true, "properties": { "companyId": { "type": "string", "description": "Tenant company ID (partition key)." }, "analysisKey": { "type": "string", "description": "Sort key identifying the record, e.g. tone_analysis, general_analysis, timing_matrix." }, "data": { "$ref": "#/components/schemas/MetricAnalysisData" }, "metadata": { "$ref": "#/components/schemas/AnalysisChunkMetadata" } } }, "RecipientOverview": { "type": "object", "additionalProperties": true, "properties": { "total_profiled": { "type": "integer", "description": "Number of recipients profiled." }, "high_confidence_count": { "type": "integer", "description": "Recipients whose position inference is high-confidence." }, "segments_count": { "type": "integer", "description": "Number of audience segments." }, "last_updated": { "type": [ "string", "null" ], "description": "When the underlying summary was last recomputed." }, "has_sufficient_data": { "type": "boolean", "description": "Whether enough data exists for reliable segment conclusions." } } }, "RecipientSegment": { "type": "object", "description": "One audience segment with response characteristics.", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Segment identifier." }, "name": { "type": "string", "description": "Display name, e.g. \"Technical Segment\"." }, "size": { "type": "integer", "description": "Number of recipients in the segment." }, "dominant_position": { "type": "string", "description": "Most common inferred position in the segment (\"unknown\" when mixed)." }, "key_insights": { "type": "array", "items": {}, "description": "Segment insight strings (or member samples in the lightweight profiler format)." }, "optimal_patterns": { "type": "object", "additionalProperties": true, "description": "Segment characteristics / optimal pattern data from the profiler." }, "confidence_level": { "type": "string", "enum": [ "high", "medium" ], "description": "high when segment size >= 10, else medium." } } }, "RecipientInsight": { "type": "object", "description": "One narrative insight about recipient behavior.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Insight type, e.g. position_pattern, segment_pattern, correlation, general." }, "title": { "type": "string", "description": "Generated user-friendly title." }, "description": { "type": "string", "description": "The insight text." }, "confidence": { "type": "string", "description": "Confidence label (defaults to \"medium\")." }, "icon": { "type": "string", "description": "PrimeNG icon class for UI rendering, e.g. pi-user." }, "actionable": { "type": "boolean", "description": "Always true in the current producer." }, "sample_size": { "type": "integer", "description": "Sample size behind the insight (0 when not tracked)." } } }, "RecipientPositionStat": { "type": "object", "description": "Aggregated per-position statistics (only positions with >= 3 profiled recipients, excluding \"unknown\"). Sorted by count descending.", "additionalProperties": true, "properties": { "position": { "type": "string", "description": "Inferred position bucket, e.g. c_suite, vp, manager, technical." }, "count": { "type": "integer", "description": "Profiled recipients in this position." }, "avg_confidence": { "type": "number", "description": "Average position-inference confidence (0-1, rounded to 2 decimals)." }, "total_responses": { "type": "integer", "description": "Total responses recorded from this position." }, "percentage": { "type": "number", "description": "Share of all profiled recipients, in percent (1 decimal)." } } }, "RecipientValidation": { "type": "object", "additionalProperties": true, "properties": { "has_significant_patterns": { "type": "boolean" }, "significant_dimensions": { "type": "array", "items": { "type": "string" }, "description": "Dimensions with statistically significant patterns (empty in the lightweight-profiler format)." }, "overall_confidence": { "type": "string", "enum": [ "high", "medium", "low" ] } } }, "RecipientChartConfig": { "type": "object", "description": "Chart.js-style chart configuration produced for UI rendering. An empty object when there is no data for the chart.", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Chart type, e.g. doughnut, bar." }, "labels": { "type": "array", "items": { "type": "string" } }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "options": { "type": "object", "additionalProperties": true } } }, "RecipientAnalysisData": { "type": "object", "description": "UI-formatted recipient analysis, produced by the intelligence pipeline's recipient profiler and stored on the recipient-summary \"main\" record. A well-formed empty structure (total_profiled 0, empty arrays) is returned when no data exists.", "additionalProperties": true, "properties": { "overview": { "$ref": "#/components/schemas/RecipientOverview" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientSegment" } }, "insights": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientInsight" } }, "position_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientPositionStat" } }, "validation": { "$ref": "#/components/schemas/RecipientValidation" }, "charts": { "type": "object", "additionalProperties": true, "properties": { "position_distribution": { "$ref": "#/components/schemas/RecipientChartConfig" }, "confidence_levels": { "$ref": "#/components/schemas/RecipientChartConfig" }, "segment_sizes": { "$ref": "#/components/schemas/RecipientChartConfig" } }, "description": "Chart-ready data series for UI rendering (empty object per chart when no data)." } } }, "RecipientProfileRecord": { "type": "object", "description": "One stored per-recipient profile row from the recipient-profiles table (written by the intelligence recipient profiler; only recipients with at least one response are stored). recipientId is a privacy-preserving 16-hex-char SHA-256 prefix of the email. Note: the current producer does not stamp a recommendation_code attribute on these rows, so the recommendationCode query filter only matches legacy rows that carry it.", "additionalProperties": true, "properties": { "companyId": { "type": "string", "description": "Tenant company ID (partition key)." }, "recipientId": { "type": "string", "description": "Hashed email identifier (sort key; first 16 hex chars of SHA-256)." }, "inferred_position": { "type": "string", "description": "Inferred position bucket (\"unknown\" when uncategorized)." }, "original_position": { "type": [ "string", "null" ], "description": "Original position text preserved when categorization fails; null/absent otherwise." }, "position_confidence": { "type": "number", "description": "Position-inference confidence, 0 to 1." }, "response_count": { "type": "integer", "description": "Responses recorded from this recipient (always >= 1 for stored rows)." }, "cluster_assignment": { "type": "integer", "description": "Cluster index from segmentation (-1 when unassigned)." }, "pattern_preferences": { "type": "object", "additionalProperties": true, "description": "Pattern-preference data from the profiler (shape owned by the intelligence pipeline)." }, "response_metrics": { "type": "object", "additionalProperties": true, "description": "Response-time pattern data. Present only on rows written by the single-profile path." }, "statistical_tests": { "type": "object", "additionalProperties": true, "description": "Per-recipient statistical test results. Present only on rows written by the single-profile path." }, "last_updated": { "type": "string", "description": "ISO 8601 timestamp of the last write." }, "email_domain": { "type": "string", "description": "Domain part of the recipient email (\"unknown\" when unavailable)." } } }, "PositionCommunicationPreferences": { "type": "object", "description": "Optimal communication preferences computed for one position from its responding messages.", "additionalProperties": true, "properties": { "optimal_word_count": { "type": "integer", "description": "Mean word count of responding messages (0 when unknown)." }, "optimal_readability": { "type": "number", "description": "Mean readability score (0 when unknown)." }, "best_time_of_day": { "type": "string", "description": "Formatted mean send time, e.g. \"3:16 PM\" (\"Unknown\" when no data)." }, "best_time_range": { "type": "string", "description": "Concentrated send-time window, e.g. \"1pm-6pm (afternoon)\" (\"Unknown\" when insufficient data)." }, "best_day_of_week": { "type": "string", "description": "Most common response day (\"Unknown\" when no data)." }, "dominant_tones": { "type": "array", "items": { "type": "string" }, "description": "Top 3 most common tones in responding messages." }, "tone_combination": { "type": "string", "description": "Most common two-tone combination, e.g. \"professional + questioning\" (\"Unknown\" when none)." }, "tone_confidence": { "type": "number", "description": "0-1 consistency score of the top tone across messages." } } }, "PositionConfidence": { "type": "object", "description": "Detailed statistical confidence for one position's breakdown, computed by the intelligence profiler against per-position sent/responded denominators over the full message set.", "additionalProperties": true, "properties": { "level": { "type": "string", "description": "Confidence level label: Very Low, Low, Medium, High, or Very High." }, "score": { "type": "number", "description": "Composite confidence score, 0-100." }, "max_score": { "type": "number", "description": "Maximum composite score (100)." }, "summary": { "type": "string", "description": "One-line reasoning summary." }, "factors": { "type": "object", "additionalProperties": true, "description": "Per-factor score contributions.", "properties": { "sample_size": { "type": "number" }, "response_consistency": { "type": "number" }, "pattern_strength": { "type": "number" }, "statistical_significance": { "type": "number" } } }, "explanations": { "type": "array", "items": { "type": "string" }, "description": "Human-readable factor explanations." }, "recommendations": { "type": "array", "items": { "type": "string" }, "description": "Actionable guidance based on the confidence level." }, "confidence_level": { "type": "number", "description": "Statistical confidence level of the interval (e.g. 0.95)." }, "margin_of_error": { "type": "number", "description": "Margin of error of the response-rate estimate (fraction)." }, "lower_bound": { "type": "number", "description": "Lower bound of the response-rate confidence interval." }, "upper_bound": { "type": "number", "description": "Upper bound of the response-rate confidence interval." }, "sample_size": { "type": "integer", "description": "Messages sent to this position (the denominator n)." }, "position_responses": { "type": "integer", "description": "Responses from this position (the numerator x)." }, "campaign_count": { "type": "integer", "description": "Distinct campaigns contributing messages." }, "effective_sample_size": { "type": "number", "description": "Clustering-adjusted effective sample size." }, "design_effect": { "type": "number", "description": "Design effect from campaign clustering." }, "quality_rating": { "type": "string", "description": "Quality label: EXCELLENT, GOOD, FAIR, or POOR." }, "display_text": { "type": "string", "description": "Pre-formatted confidence sentence for display." }, "adequate_sample": { "type": "boolean", "description": "Whether the sample passes the normal-approximation adequacy gate. False means the numbers are suggestive, not statistically validated." } } }, "PositionBreakdownEntry": { "type": "object", "description": "Per-position statistics for one recommendation, produced by the intelligence recommendation recipient profiler.", "additionalProperties": true, "properties": { "response_count": { "type": "integer", "description": "Responding messages attributed to this position for the recommendation." }, "unique_recipients": { "type": "integer", "description": "Distinct recipients behind those responses." }, "response_rate_for_position": { "type": [ "number", "null" ], "description": "P(response | position) = responders / messages sent to this position over the full message set, rounded to 4 decimals. Null when the denominator is unavailable (never fabricated)." }, "communication_preferences": { "$ref": "#/components/schemas/PositionCommunicationPreferences" }, "confidence": { "$ref": "#/components/schemas/PositionConfidence" }, "original_position_texts": { "type": "array", "items": { "type": "string" }, "description": "Original position strings that resolved to \"unknown\". Present only on the unknown bucket." } } }, "RecommendationPositionProfile": { "type": "object", "description": "Position breakdown for one recommendation code, as stored on recipient-summary recommendation_position_breakdown_{code} rows by the intelligence pipeline (and merged across companies for agency views by the analytics service).", "additionalProperties": true, "properties": { "recommendation_code": { "type": "string", "description": "The recommendation code this profile belongs to, e.g. TA-1." }, "metric": { "type": "string", "description": "Human-readable metric/strategy string for the recommendation (may embed a response-rate summary)." }, "total_responses": { "type": "integer", "description": "Responding messages matched to this recommendation's pattern." }, "position_breakdown": { "type": "object", "description": "Per-position statistics keyed by position bucket (e.g. c_suite, vp, manager, technical, unknown).", "additionalProperties": { "$ref": "#/components/schemas/PositionBreakdownEntry" } }, "consolidated_messaging_guide": { "type": "object", "additionalProperties": true, "description": "Unified messaging guide consolidated across the validated positions (timing, word count, tone guidance and a confidence_level). Shape owned by the intelligence profiler." } } }, "PositionRecommendationSummary": { "type": "object", "description": "One recommendation's contribution to a consolidated position row.", "additionalProperties": true, "properties": { "recommendation_code": { "type": "string", "description": "Base code with any numeric suffix stripped, e.g. TA." }, "full_recommendation_code": { "type": "string", "description": "Full code, e.g. TA-1." }, "metric": { "type": "string", "description": "Metric/strategy string (defaults to \"recommendation\")." }, "response_count": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence": { "type": "object", "additionalProperties": true, "description": "The per-position confidence object for this recommendation (see PositionConfidence)." }, "communication_preferences": { "type": "object", "additionalProperties": true, "description": "The per-position communication preferences for this recommendation (see PositionCommunicationPreferences)." } } }, "ConsolidatedCommunicationPreferences": { "type": "object", "description": "Communication preferences consolidated across all recommendations for one position (most-common values win; word count / readability averaged).", "additionalProperties": true, "properties": { "best_day_of_week": { "type": "string", "description": "\"Unknown\" when no data." }, "best_time_of_day": { "type": "string", "description": "\"Unknown\" when no data." }, "best_time_range": { "type": "string", "description": "\"Unknown\" when no data." }, "optimal_word_count": { "type": "integer", "description": "Average optimal word count (0 when unknown)." }, "optimal_readability": { "type": "integer", "description": "Average optimal readability (0 when unknown)." }, "dominant_tones": { "type": "array", "items": { "type": "string" }, "description": "Up to 3 distinct dominant tones." }, "tone_combination": { "type": "string", "description": "Best-performing tone or tone combination parsed from the top tone recommendation, e.g. \"professional + urgent\" (\"Unknown\" when unparseable)." }, "tone_source": { "type": "string", "enum": [ "recommendation", "aggregated" ], "description": "Whether the tone came from a tone recommendation or aggregated message data." }, "tone_recommendation_meta": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Performance metadata of the tone recommendation the tone was taken from; null when tone came from aggregation.", "properties": { "recommendation_code": { "type": "string" }, "response_count": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence": { "type": "object", "additionalProperties": true }, "metric": { "type": "string", "description": "Metric string with emojis stripped." } } } } }, "ConsolidatedConfidence": { "type": "object", "description": "Aggregate confidence for one position row, averaged across its recommendations and capped by sample-size penalties (<30 responses caps at Medium, <15 at Low, <10 forces Very Low).", "additionalProperties": true, "properties": { "score": { "type": "integer", "description": "Adjusted confidence score, 0-100." }, "level": { "type": "string", "description": "Adjusted level: Very Low, Low, Medium, High, or Very High." }, "display_text": { "type": "string", "description": "Same as level." }, "based_on_recommendations": { "type": "integer", "description": "Number of recommendations aggregated." }, "sample_size": { "type": "integer", "description": "Highest per-recommendation response count for this position (not a sum, to avoid double-counting)." }, "unique_recipients": { "type": "integer" }, "quality_rating": { "type": "string", "enum": [ "EXCELLENT", "GOOD", "FAIR", "POOR" ] }, "sample_size_limited": { "type": "boolean", "description": "True when fewer than 30 responses forced a confidence downgrade." }, "original_level": { "type": "string", "description": "Most common per-recommendation level before the sample-size penalty." } } }, "PositionConsolidatedRow": { "type": "object", "description": "One consolidated per-position row produced by the analytics position-breakdown transformation (grouping every recommendation's data for that position). Rows are sorted by total_responses descending.", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "analysis_type": { "type": "string", "description": "position_consolidated_{position}." }, "analysisKey": { "type": "string", "description": "position_profile_{position}." }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "properties": { "position": { "type": "string", "description": "Position bucket name." }, "total_responses": { "type": "integer", "description": "Highest per-recommendation response count for this position." }, "unique_recipients": { "type": "integer" }, "recommendation_count": { "type": "integer" }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/PositionRecommendationSummary" }, "description": "Contributing recommendations, sorted by response count descending." }, "consolidated_communication_preferences": { "$ref": "#/components/schemas/ConsolidatedCommunicationPreferences" }, "confidence": { "$ref": "#/components/schemas/ConsolidatedConfidence" }, "sourceCompanies": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "companyType": { "type": "string" }, "responseCount": { "type": "integer" }, "recommendationCount": { "type": "integer" }, "confidence": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Per-company aggregated confidence with the same sample-size penalties; null when no scores were available." } } }, "description": "Present only in agency (multi-company) views: per-company contribution to this position row, sorted by responseCount descending." } } }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "position": { "type": "string" }, "recommendation_count": { "type": "integer" }, "total_responses": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "confidence_level": { "type": "string", "description": "Most common level before the sample-size penalty." } } }, "ui_data": { "type": "object", "additionalProperties": true, "description": "Compact UI projection of the same row.", "properties": { "position": { "type": "string" }, "total_responses": { "type": "integer" }, "unique_recipients": { "type": "integer" }, "recommendations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": "string" }, "full_code": { "type": "string" }, "metric": { "type": "string" }, "response_count": { "type": "integer" } } } }, "communication_preferences": { "$ref": "#/components/schemas/ConsolidatedCommunicationPreferences" }, "confidence": { "type": "string", "description": "Most common confidence level label." } } } } }, "PositionBreakdownSummary": { "type": "object", "additionalProperties": true, "properties": { "total_recommendations": { "type": "integer", "description": "Recommendation codes with stored position profiles." }, "total_position_entries": { "type": "integer", "description": "Consolidated position rows produced." }, "recommendations_with_data": { "type": "integer", "description": "Recommendations whose position_breakdown is non-empty." } } }, "PositionBreakdownPayload": { "type": "object", "description": "The analytics service's full position-breakdown payload. NOTE: because the public API wraps the analytics Lambda's entire response body, this whole payload appears under the outer `data.data` key; the sibling breakdown_by_recommendation and summary at the outer level are envelope artifacts that currently always hold empty defaults \u2014 read the populated values from inside this object.", "additionalProperties": true, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionConsolidatedRow" }, "description": "Consolidated per-position rows, sorted by total_responses descending." }, "breakdown_by_recommendation": { "type": "object", "description": "Position profiles keyed by recommendation code (e.g. TA-1, DOW-2).", "additionalProperties": { "$ref": "#/components/schemas/RecommendationPositionProfile" } }, "summary": { "$ref": "#/components/schemas/PositionBreakdownSummary" }, "generated_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string" }, "perCompanySummary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "companyType": { "type": "string" }, "hasData": { "type": "boolean" }, "recommendationCount": { "type": "integer" } } }, "description": "Present only in agency (multi-company) views: per-company data availability." } } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current burst window (default 200 per 15 minutes per key).", "schema": { "type": "string" } }, "RateLimitRemaining": { "description": "Requests remaining in the current burst window.", "schema": { "type": "string" } }, "RateLimitReset": { "description": "Seconds until the burst window resets.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying. Rejected calls do not consume monthly quota.", "schema": { "type": "integer" } }, "RateLimitPolicy": { "description": "Static description of the burst quota policy: \";w=\". Present on every response, including unauthenticated errors.", "schema": { "type": "string", "examples": [ "200;w=900" ] } } } } }