Strategic brief API

The strategic brief (Strategic Direction) is the workspace’s master business document, mission, goals, SWOT, finances, org chart, systems, and 100+ structured fields stored on business_briefs. GET returns the full row; PATCH accepts any allowlisted column (see field reference below).

Endpoints

• GET /strategic-brief, get latest brief (or specific brief with ?briefId=)

• PATCH /strategic-brief, partial update of allowlisted fields

Scopes and permissions

• brief:read for GET; brief:write for PATCH

• Token owner must have read (GET) or update (PATCH) permission on the Strategic Direction workspace page

Existing MCP OAuth connections created before brief:read / brief:write were added must reconnect to grant the new scopes.

Get strategic brief (GET /strategic-brief)

• Without briefId, returns the latest brief for the workspace

• briefId (query), optional UUID of a specific business_briefs row

curl "https://api.elevale.app/v1/workspaces/{workspaceId}/strategic-brief" \
  -H "Authorization: Bearer elv_pat_..."

Example GET response

{
  "data": {
    "brief": {
      "id": "uuid",
      "business_name": "Acme Ltd",
      "mission_statement": "Help SMEs scale with clarity",
      "short_term_goals": [{ "title": "Grow MRR", "description": "20% growth", "status": "identified" }],
      "swot_strengths": [{ "text": "Expert team", "description": "Deep sector experience" }],
      "financial_metrics": { "currentMonthlyTurnover": 85000, "netMargin": 12 },
      "staff_members": [{ "id": "ceo-1", "name": "Alex Morgan", "role": "CEO" }],
      "sector": "Professional services",
      "version": 3,
      "updated_at": "2026-07-29T12:00:00.000Z"
    }
  },
  "meta": { "requestId": "..." }
}

Field names use snake_case matching database columns. The response includes every column on the row, use the field reference below to interpret values. Complex fields are JSON (arrays or objects) stored as jsonb.

Update strategic brief (PATCH /strategic-brief)

Send only the fields you want to change. Preferred shape wraps fields in updates; top-level allowlisted fields are also accepted. camelCase keys (e.g. missionStatement) are normalized to snake_case when they match an allowlisted column.

PATCH body

• briefId (optional), target brief UUID; defaults to latest

• updates (preferred), object of field → value pairs

• Or top-level fields, e.g. mission_statement, swot_strengths without wrapping in updates

• senderAs / mcpClientName (optional), MCP attribution; ignored for column mapping

curl -X PATCH "https://api.elevale.app/v1/workspaces/{workspaceId}/strategic-brief" \
  -H "Authorization: Bearer elv_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"updates":{"mission_statement":"Help SMEs scale with clarity","swot_strengths":[{"text":"Expert team","description":"Deep sector experience"}]}}'

JSON shapes for common complex fields

// Goals
"short_term_goals": [
  { "title": "Grow recurring revenue", "description": "Target 20% MRR growth", "status": "identified" }
]

// SWOT item
"swot_strengths": [
  { "text": "Expert team", "description": "Deep sector experience across leadership" }
]

// USP
"unique_selling_points": [
  { "text": "Done-for-you implementation", "status": "Unique" }
]

// Business challenge
"key_business_challenges": [
  { "text": "Capacity constraints", "description": "Delivery team at 95% utilisation", "status": "High" }
]

// Org chart member (send full staff_members array when replacing)
"staff_members": [
  { "id": "ceo-1", "name": "Alex Morgan", "role": "CEO", "email": "[email protected]", "parentId": null }
]

// Financial metrics (partial example)
"financial_metrics": {
  "currentMonthlyTurnover": 85000,
  "netMargin": 12,
  "grossMargin": 45,
  "debtorDays": 32
}

When updating array fields (goals, SWOT, staff_members, USPs), send the complete array you want stored, the API replaces the column value; it does not merge individual array items.

Full field reference (PATCH allowlist)

Only columns listed here can be updated via PATCH. Unknown keys are silently ignored. Grouped by Strategic Direction section.

Identity & mission

Core business identity shown at the top of Strategic Direction.

• business_name (string), Legal or trading name of the business.

• mission_statement (string), Mission statement, why the business exists.

• core_values (string[]), List of core values (plain strings).

• sector (string), Industry or sector label.

• company_details (object), Structured company profile (addresses, registration, contacts). Shape matches in-app Company Details section.

• is_draft (boolean), When true, brief is marked as draft in the workspace.

Goals

Short- and long-term strategic goals. Each goal may be a plain string or { title, description?, status? }.

• short_term_goals (string[] | object[]), Near-term goals. Prefer { title, description, status } objects; legacy string entries are supported.

• long_term_goals (string[] | object[]), Long-term goals. Same shape as short_term_goals.

• goal_details (string), Free-text elaboration on goals and priorities.

• short_term_goals_status (object), Per-goal status metadata keyed by goal id or index.

• long_term_goals_status (object), Per-goal status metadata for long-term goals.

Challenges & situational analysis

• key_business_challenges (object[]), Primary challenges as { text, description?, status } where status is High | Medium | Low.

• business_challenges (object[]), Additional challenge list (same shape as key_business_challenges).

• situational_analysis (string), Market context, competitive landscape, and business environment narrative.

• improvement_areas (string | object), Areas targeted for improvement.

• business_dependency (string), Key dependencies (people, systems, clients) the business relies on.

SWOT analysis

Each SWOT array holds { text, description? } items. Removed items are archived in removed_swot_* arrays. Status objects track review state.

• swot_strengths (object[]), Strengths, { text, description? }.

• swot_weaknesses (object[]), Weaknesses, { text, description? }.

• swot_opportunities (object[]), Opportunities, { text, description? }.

• swot_threats (object[]), Threats, { text, description? }.

• removed_swot_strengths (object[]), Archived strengths removed from the active list.

• removed_swot_weaknesses (object[]), Archived weaknesses.

• removed_swot_opportunities (object[]), Archived opportunities.

• removed_swot_threats (object[]), Archived threats.

• swot_strengths_status (object), Review/status metadata for strengths.

• swot_weaknesses_status (object), Review/status metadata for weaknesses.

• swot_opportunities_status (object), Review/status metadata for opportunities.

• swot_threats_status (object), Review/status metadata for threats.

Market, customers & positioning

• target_audience (string[]), Audience segments (plain strings or labels).

• target_audience_distribution (object[]), Weighted segments, { segment, percentage, category? }.

• unique_selling_points (object[]), USPs, { text, status } where status is Unique | Competitive | Not Relevant | Losing.

• removed_unique_selling_points (object[]), Archived USPs removed from the active list.

• ideal_clients (string[] | object[]), Ideal client profiles, strings or rich IdealClientProfile objects (demographics, psychographics, approach strategy).

• competitors (object | object[]), Competitor analysis data from Strategic Direction.

• client_retention_methods (string[]), Methods used to retain clients.

• has_client_retention_methods (boolean), Whether formal client retention methods exist.

• has_repeat_value_products (boolean), Whether the business offers repeat-value products or services.

• repeat_value_products_details (string), Details on repeat-value offerings.

Partners & promotion

• strategic_partners (string[]), Legacy list of partner names.

• strategic_partners_v2 (object), { active: string[], pursued: string[], reach: home_counties | national | global | null }.

• promotion_methods (string[]), Legacy promotion channel list.

• promotion_methods_v2 (object[]), Promotion methods, { method, category } where category is Digital | Traditional | Direct | Relationships | Other.

Operations & systems

• sales_systems (string), How sales is managed (CRM, pipeline, process).

• marketing_systems (string), Marketing tools and processes.

• operational_systems (string), Day-to-day operational systems.

• financial_systems (string), Accounting, invoicing, and financial tooling.

• admin_systems (string), Admin and back-office systems.

• business_software (object[]), Software stack, { name, description?, category?, websiteUrl?, logoUrl? }.

• workflow_consistency (string), How consistently workflows are followed.

• sop_implementation (string), SOP adoption and implementation notes.

• sop_accessibility (string), How staff access and use SOPs.

• operational_radius (number), Service radius in miles/km (used with location fields).

• central_location (string), Primary operating location label.

Financial

• financial_analysis (string), Narrative financial overview and commentary.

• financial_metrics (object), Turnover, margins, debtor/creditor days, turnover history, etc., { currentMonthlyTurnover, accountPeriodEnd, turnoverHistory, netMargin, grossMargin, debtorDays, creditorDays, quickRatio, directorsLoanAccount }.

• financial_kpi_refs (object), Links to workspace KPIs used for financial tracking.

• generated_financial_analysis (string), AI-generated financial analysis (read-only in UI; PATCH overwrites if sent).

• remuneration_setup (object), { salary: number, dividends: number }, owner remuneration split.

Capacity, location & growth

• capacity_tracking (string), How capacity is monitored.

• capacity_metrics (object), Capacity snapshot, { currentCapacity, maxProjectCapacity, currentProjectCount, centralLocation, operationalRadius, mapData, locationPins[] }.

• working_within_zone (boolean), Whether the business operates within a defined service zone.

• zone_benefits (string), Benefits of operating within the zone.

• quiet_periods (string), Seasonal or cyclical quiet periods.

• expansion_readiness (string), Readiness for geographic or market expansion.

• scalability (string), How the business scales operations.

• growth_bottlenecks (string), Constraints limiting growth.

Organisation & staff structure

staff_members powers the org chart. Always PATCH the full array when replacing structure, partial array merges are not supported.

• organizational_structure (string), Narrative description of org structure (also reflected in org chart).

• staff_members (object[]), Org chart nodes, { id, name, role, email?, department?, parentId?, reportsTo?, responsibilities?, showInHierarchy?, ... }.

• office_support (string), Office-based support roles and coverage.

• onsite_support (string), On-site / field support arrangements.

• efficient_sections (string), Best-performing teams or departments.

• poor_performing_sections (string), Underperforming areas needing attention.

Staff retention & development

• staff_retention (string), Legacy retention summary text.

• staff_retention_strategy (string), Retention strategy narrative.

• staff_retention_issues (string), Known retention issues.

• staff_retention_marketing (string), Internal marketing used for retention.

• has_staff_retention_strategy (boolean), Toggle, formal retention strategy exists.

• offers_training_development (boolean), Toggle, training and development offered.

• uses_retention_marketing (boolean), Toggle, retention marketing in use.

• has_staff_leaving_issues (boolean), Toggle, experiencing staff attrition issues.

• measures_employee_satisfaction (boolean), Toggle, employee satisfaction is measured.

• recognizes_staff_performance (boolean), Toggle, performance recognition programme exists.

• employee_satisfaction (string), How satisfaction is measured and recent results.

• employee_recognition (string), Recognition programmes and practices.

• training_and_development (string), L&D approach, budgets, and cadence.

Staff recruitment

• is_currently_recruiting (boolean), Toggle, actively recruiting.

• has_recruitment_difficulties (boolean), Toggle, facing hiring difficulties.

• uses_recruitment_channels (boolean), Toggle, uses defined recruitment channels.

• has_formal_recruitment_process (boolean), Toggle, documented recruitment process exists.

• staff_recruiting_details (string), Current open roles and hiring priorities.

• recruitment_channels (string), Channels used (agencies, LinkedIn, referrals, etc.).

• staff_recruitment_process (string), Step-by-step recruitment process.

• staff_sourcing_challenges (string), Challenges finding suitable candidates.

Leadership & feedback

• leadership_effectiveness (string), Leadership structure and effectiveness notes.

• feedback_gathering (string), How employee and customer feedback is collected and used.

• gathers_feedback (boolean), Toggle, formal feedback gathering in place.

• has_effective_leadership (boolean), Toggle, leadership considered effective.

Compliance & accreditations

• accreditations (object[]), Workspace accreditations/certifications tracked in Strategic Direction.

• targeted_certification_ids (string[]), UUIDs of certification journeys the workspace is pursuing.

• collateral_audit (object), Marketing collateral audit data (may include HTML notes fields).

Extended / internal

Rarely needed for integrations. additional_data is a catch-all JSON bag.

• additional_data (object), Arbitrary JSON extension bucket for custom integrations.

• saint_commentary (string), AI advisor commentary stored on the brief.

• saint_global_message (string), Global advisor message field.

• has_saint_global_support (boolean), Whether Saint Global support is enabled.

Immutable & server-managed fields

• Ignored on PATCH: id, workspace_id, version, created_at

• Set server-side: updated_by, updated_at

• A minor BD log entry is recorded on successful PATCH

Example PATCH success response

{
  "data": {
    "message": "Updated strategic brief",
    "briefId": "uuid"
  },
  "meta": { "requestId": "..." }
}

Recommended workflow

• GET /strategic-brief (or getStrategicBrief via MCP) to read current values

• PATCH only changed fields inside { updates: { ... } }

• For org chart or SWOT edits, copy the existing array from GET, modify, and send the full array back

• GET again to confirm persistence

MCP tools

• getStrategicBrief, returns full brief object (scope brief:read). Optional briefId query param.

• updateStrategicBrief, PATCH with { updates: { field: value } } (scope brief:write). Always call getStrategicBrief first.

Related

Personal access tokens (PATs) · Scopes and permissions · OpenAPI reference