Skip to main content
PathmodePathmode
Our ApproachFor Product TeamsBlogDevelopers

Developer Docs

Integrate your AI agents with Pathmode. REST API, MCP tools, and everything you need to connect your development workflow to your Intent Layer.

Getting StartedREST APIMCP ToolsData Models

Getting Started

The Pathmode MCP server connects your AI coding agent to your workspace — giving it access to intents, evidence, and product context. You can be up and running in under a minute.

1. Get your API key

Go to pathmode.io and navigate to Settings → API Keys. Create a new key and copy it — you will not be able to see it again.

2. Install the MCP server

The fastest way to get started is auto setup. This configures your MCP client automatically:

bash
npx @pathmode/mcp-server@latest setup pm_live_...

Alternatively, add the server manually to your MCP client configuration file (e.g. claude_desktop_config.json or .mcp.json):

json•claude_desktop_config.json
{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["-y", "@pathmode/mcp-server@latest"],
      "env": {
        "PATHMODE_API_KEY": "pm_live_..."
      }
    }
  }
}

Or pass the key directly as an environment variable:

bash
PATHMODE_API_KEY=pm_live_... npx @pathmode/mcp-server

Authentication

All API requests require a valid API key passed in the Authorization header using the Bearer scheme. Keys are prefixed with pm_live_.

Base URL

text
https://pathmode.io/api/v1

Example request

bash
curl https://pathmode.io/api/v1/workspaces \
  -H "Authorization: Bearer pm_live_..."

Error codes

StatusMeaning
401Invalid or expired API key. Check that your key is correct and has not been revoked.
403Insufficient scope. The key does not have permission for the requested resource.

REST API Reference

Intents

GET/api/v1/intents

List all intents in the workspace. Optionally filter by lifecycle status.

Query Parameters
NameTypeDescription
statusstringFilter by status: draft | validated | approved | shipped | verified
Example
bash
curl https://pathmode.io/api/v1/intents?status=approved \
  -H "Authorization: Bearer pm_live_..."
Response
json
{
  "intents": [
    {
      "id": "int_abc123",
      "title": "Improve onboarding flow",
      "status": "approved",
      "objective": "New users drop off before reaching value...",
      "productId": "prod_xyz",
      "outcomes": ["User completes setup in < 3 min", "..."],
      "problemSeverity": "high",
      "createdAt": "2026-03-10T08:00:00Z",
      "updatedAt": "2026-03-18T14:22:00Z"
    }
  ],
  "count": 1
}
POST/api/v1/intents

Create a new intent spec. Only title, objective, and productId are required — add outcomes, constraints, and edge cases as the spec matures.

Request Body
FieldTypeDescription
title*stringShort name for the intent
objective*stringWhy this matters — the problem and who has it
productId*stringProduct (Space) this intent belongs to
outcomesstring[]Observable, testable state changes
constraintsstring[]Hard limits the implementation must respect
healthMetricsstring[]What to monitor after shipping
edgeCases{scenario, expectedBehavior}[]Failure modes and boundary conditions
verificationobjectPlan with manualChecks?, unitTests?, e2eTests?
problemSeveritystringlow | medium | high | critical
Example
bash
curl -X POST https://pathmode.io/api/v1/intents \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Improve onboarding flow",
    "objective": "New users drop off at step 2 of setup...",
    "productId": "prod_xyz",
    "outcomes": ["User completes setup in < 3 min"],
    "problemSeverity": "high"
  }'
Response
json
{
  "id": "int_abc123",
  "title": "Improve onboarding flow",
  "status": "draft",
  "objective": "New users drop off at step 2 of setup...",
  "productId": "prod_xyz",
  "outcomes": ["User completes setup in < 3 min"],
  "problemSeverity": "high",
  "createdAt": "2026-03-24T10:00:00Z",
  "updatedAt": "2026-03-24T10:00:00Z"
}
GET/api/v1/intents/:id

Get a single intent with full details including edge cases, linked evidence, and dependency relations.

Example
bash
curl https://pathmode.io/api/v1/intents/int_abc123 \
  -H "Authorization: Bearer pm_live_..."
Response
json
{
  "id": "int_abc123",
  "title": "Improve onboarding flow",
  "status": "approved",
  "objective": "New users drop off at step 2...",
  "outcomes": ["User completes setup in < 3 min"],
  "constraints": ["Must not require email verification"],
  "edgeCases": [
    { "scenario": "User closes browser mid-setup", "expectedBehavior": "Progress is saved" }
  ],
  "evidence": [{ "id": "ev_001", "content": "...", "type": "friction" }],
  "relations": { "dependsOn": [], "enables": ["int_def456"] },
  "...": "..."
}
PATCH/api/v1/intents/:id

Update intent content. Does not change status — use the status endpoint for lifecycle transitions. Provide only the fields you want to change.

Request Body
FieldTypeDescription
titlestringUpdated title
objectivestringUpdated objective
outcomesstring[]Replace all outcomes
constraintsstring[]Replace all constraints
edgeCases{scenario, expectedBehavior}[]Replace all edge cases
healthMetricsstring[]Replace all health metrics
verificationobjectReplace verification plan
problemSeveritystringlow | medium | high | critical
Example
bash
curl -X PATCH https://pathmode.io/api/v1/intents/int_abc123 \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "outcomes": [
      "User completes setup in < 3 min",
      "Setup completion rate > 80%"
    ]
  }'
Response
json
{
  "id": "int_abc123",
  "title": "Improve onboarding flow",
  "status": "approved",
  "outcomes": [
    "User completes setup in < 3 min",
    "Setup completion rate > 80%"
  ],
  "updatedAt": "2026-03-24T11:00:00Z",
  "...": "..."
}
PATCH/api/v1/intents/:id/status

Transition an intent to a new lifecycle status. For shipped and verified transitions, the response includes a verification checklist of outcomes, constitution rules, and health metrics to confirm.

Request Body
FieldTypeDescription
status*stringNew status: draft | validated | approved | shipped | verified
Example
bash
curl -X PATCH https://pathmode.io/api/v1/intents/int_abc123/status \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "shipped" }'
Response
json
{
  "id": "int_abc123",
  "status": "shipped",
  "verificationChecklist": {
    "outcomes": [
      { "text": "User completes setup in < 3 min", "confirmed": false }
    ],
    "constitutionRules": [
      { "rule": "All changes must be backwards-compatible", "confirmed": false }
    ]
  }
}
POST/api/v1/intents/:id/notes

Record a technical decision or implementation note for an intent. Useful for documenting why a specific approach was chosen.

Request Body
FieldTypeDescription
note*stringThe implementation note or technical decision
sourcestringOrigin of the note (default: "mcp")
Example
bash
curl -X POST https://pathmode.io/api/v1/intents/int_abc123/notes \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Chose progressive disclosure over wizard — fewer clicks for power users",
    "source": "mcp"
  }'
Response
json
{
  "id": "note_789",
  "intentId": "int_abc123",
  "note": "Chose progressive disclosure over wizard...",
  "source": "mcp",
  "createdAt": "2026-03-24T11:30:00Z"
}
POST/api/v1/intents/:id/evidence

Link or unlink evidence items to/from an intent. Establishes traceability between user problems and planned solutions.

Request Body
FieldTypeDescription
linkstring[]Evidence IDs to link to this intent
unlinkstring[]Evidence IDs to unlink from this intent
Example
bash
curl -X POST https://pathmode.io/api/v1/intents/int_abc123/evidence \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "link": ["ev_001", "ev_002"],
    "unlink": ["ev_003"]
  }'
Response
json
{
  "intentId": "int_abc123",
  "linked": ["ev_001", "ev_002"],
  "unlinked": ["ev_003"]
}
POST/api/v1/intents/:id/verify

AI-grade your implementation against the intent spec. Checks each outcome, constraint, constitution rule, and edge case. Returns pass/fail per item with reasoning and an overall score.

Request Body
FieldTypeDescription
summary*stringDescription of what was implemented and how
codeChangesstringSummary of code changes (file list, key modifications)
Example
bash
curl -X POST https://pathmode.io/api/v1/intents/int_abc123/verify \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Implemented progressive onboarding with 3-step flow...",
    "codeChanges": "components/Onboarding.tsx, lib/onboarding-state.ts"
  }'
Response
json
{
  "pass": true,
  "score": 0.92,
  "results": [
    { "item": "User completes setup in < 3 min", "type": "outcome", "pass": true, "reasoning": "..." },
    { "item": "Must not require email verification", "type": "constraint", "pass": true, "reasoning": "..." }
  ],
  "summary": "Implementation satisfies 11/12 checks..."
}

Evidence

GET/api/v1/evidence

Search and filter evidence items across a product. Supports text search, type filtering, severity filtering, and pagination.

Query Parameters
NameTypeDescription
productIdstringFilter by product ID
typestringfriction | quote | observation | metric | request
severitystringlow | medium | high | critical
searchstringFull-text search across evidence content
tagsstringComma-separated tags to filter by
limitnumberMax results (default 50, max 200)
offsetnumberPagination offset
Example
bash
curl "https://pathmode.io/api/v1/evidence?productId=prod_xyz&type=friction&severity=high" \
  -H "Authorization: Bearer pm_live_..."
Response
json
{
  "evidence": [
    {
      "id": "ev_001",
      "content": "Users report confusion at the pricing toggle",
      "type": "friction",
      "severity": "high",
      "productId": "prod_xyz",
      "source": "Support ticket",
      "tags": ["Pricing", "UX"],
      "createdAt": "2026-03-15T09:00:00Z"
    }
  ],
  "count": 1
}
POST/api/v1/evidence

Create a new evidence item. Evidence can later be linked to intents to support prioritization and traceability.

Request Body
FieldTypeDescription
content*stringThe evidence content — a finding, quote, or observation
type*stringfriction | quote | observation | metric | request
productId*stringProduct this evidence belongs to
sourcestringWhere this came from (e.g., "User interview", "Bug report")
sourceUrlstringURL to the original source
severitystringlow | medium | high | critical (required for friction type)
sentimentstringpositive | negative | neutral | mixed
tagsstring[]Category tags (e.g., ["Onboarding", "Performance"])
stagestringUser journey stage (e.g., "Discovery", "Checkout")
Example
bash
curl -X POST https://pathmode.io/api/v1/evidence \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Users report confusion at the pricing toggle",
    "type": "friction",
    "productId": "prod_xyz",
    "severity": "high",
    "source": "Support ticket",
    "tags": ["Pricing", "UX"]
  }'
Response
json
{
  "id": "ev_002",
  "content": "Users report confusion at the pricing toggle",
  "type": "friction",
  "severity": "high",
  "productId": "prod_xyz",
  "source": "Support ticket",
  "tags": ["Pricing", "UX"],
  "createdAt": "2026-03-24T12:00:00Z"
}

Workspace

GET/api/v1/workspace

Get workspace details including strategy (vision, non-negotiables, architecture principles), active products, and constitution rules. The strategy and product manifest inform AI-grading during verification.

Example
bash
curl https://pathmode.io/api/v1/workspace \
  -H "Authorization: Bearer pm_live_..."
Response
json
{
  "id": "ws_001",
  "name": "Acme Product",
  "urlKey": "acme",
  "tags": ["saas", "b2b"],
  "strategy": {
    "vision": "The simplest way to manage product intent",
    "tradeoffs": ["Speed over completeness"],
    "nonNegotiables": ["All changes must be backwards-compatible"],
    "architecturePrinciples": ["Server components by default"]
  },
  "products": [
    {
      "id": "prod_xyz",
      "name": "Checkout",
      "slug": "checkout",
      "productVision": "Remove purchase hesitation at the final step",
      "northStar": "Payment completion succeeds without confusion",
      "targetAudience": "Growth PM, checkout engineers",
      "manifest": {
        "constraints": ["No third-party scripts before user intent"],
        "principles": ["Clarity over cleverness"],
        "keyDecisions": ["Use hosted payment fields"]
      }
    }
  ],
  "constitutionRules": [
    { "id": "cr_01", "rule": "All changes must be backwards-compatible" },
    { "id": "cr_02", "rule": "No breaking API changes without migration path" }
  ]
}
GET/api/v1/workspace/constitution

Get just the workspace constitution rules. These are mandatory constraints that all implementations must respect and are checked during intent verification.

Example
bash
curl https://pathmode.io/api/v1/workspace/constitution \
  -H "Authorization: Bearer pm_live_..."
Response
json
{
  "constitutionRules": [
    { "id": "cr_01", "rule": "All changes must be backwards-compatible" },
    { "id": "cr_02", "rule": "No breaking API changes without migration path" }
  ]
}

Export

GET/api/v1/export

Export workspace context as formatted text. Use "claude-md" for a full CLAUDE.md file, "cursorrules" for Cursor AI rules, or "intent-md" for a single intent specification file. For cursorrules/intent-md, product context is derived from the resolved intent. For claude-md, pass product_id to select a specific product (defaults to first active product).

Query Parameters
NameTypeDescription
format*stringclaude-md | cursorrules | intent-md
intent_idstringIntent ID (required for intent-md, optional for cursorrules)
product_idstringProduct ID (optional, only used for claude-md to select a specific product)
Example
bash
curl "https://pathmode.io/api/v1/export?format=claude-md" \
  -H "Authorization: Bearer pm_live_..."
Response
json
# Acme Product — Workspace Context

## Strategy
Vision: The simplest way to manage product intent
...

## Constitution
- All changes must be backwards-compatible
...

## Active Intents
### Improve onboarding flow (approved)
...

Read Tools

Query intents, evidence, workspace strategy, and the dependency graph. All read tools are safe to call in any context — they never modify data.

get_current_intent

Get the currently active intent (first approved, or most recently updated).

ParameterTypeDescription
statusstringFilter by status: draft, validated, approved, shipped, verified

list_intents

List all intents in the workspace with their status, objectives, and metadata.

ParameterTypeDescription
statusstringFilter by status: draft, validated, approved, shipped, verified

get_intent

Get a single intent by ID with full details including objective, outcomes, constraints, edge cases, and relations.

ParameterTypeDescription
intentId*stringThe intent ID to fetch

get_intent_relations

Get the dependency graph for a specific intent. Shows what it depends on, enables, or blocks.

ParameterTypeDescription
intentId*stringThe intent ID to get relations for

search_intents

Search intents by keyword across user goals, objectives, outcomes, and constraints.

ParameterTypeDescription
query*stringSearch keyword or phrase
statusstringFilter by status

analyze_intent_graph

Analyze the intent dependency graph for risks and strategic insights. Returns critical path, cycles, bottlenecks, orphans, and stalled intents.

ParameterTypeDescription
analysis"full" | "critical-path" | "risks" | "status"Type of analysis to run. Defaults to full.

export_context

Export workspace context as a formatted file for AI agent consumption. For cursorrules/intent-md, product context is derived from the resolved intent. For claude-md, pass productId to select a specific product (defaults to first active product).

ParameterTypeDescription
format*"claude-md" | "cursorrules" | "intent-md"Export format
intentIdstringIntent ID (optional, for cursorrules and intent-md)
productIdstringProduct ID (optional, only used for claude-md to select a specific product)

get_agent_prompt

Get a formatted execution prompt for a specific intent with objective, outcomes, constraints, edge cases, and verification steps.

ParameterTypeDescription
intentId*stringThe intent ID to generate a prompt for
mode"draft" | "execute"draft = critique the spec, execute = implement it

get_workspace

Get workspace details including strategy (vision, non-negotiables, architecture principles), active products, and constitution rules.

No input parameters required.

get_constitution

Get the workspace constitution rules. These are mandatory constraints that all implementations must respect.

No input parameters required.

query_evidence

Search evidence items (friction points, user quotes, observations, metrics, feature requests) by product, type, severity, or text.

ParameterTypeDescription
productIdstringFilter by product ID
type"friction" | "quote" | "observation" | "metric" | "request"Filter by evidence type
severity"low" | "medium" | "high" | "critical"Filter by severity
searchstringText search across evidence content
tagsstringComma-separated tags to filter by
limitnumberMax results (default 50, max 200)

Example: search for intents related to onboarding

json
// Tool call: search_intents
{
  "query": "onboarding",
  "status": "approved"
}

Write Tools

Create and modify intents, evidence, and implementation notes. Write tools require a valid API key with write permissions.

update_intent_status

Update the status of an intent. For shipped/verified transitions, returns a verification checklist.

ParameterTypeDescription
intentId*stringThe intent ID to update
status*"draft" | "validated" | "approved" | "shipped" | "verified"The new status

log_implementation_note

Record a technical decision or implementation note for an intent.

ParameterTypeDescription
intentId*stringThe intent ID to attach the note to
note*stringThe implementation note or technical decision

create_intent

Create a new intent spec in the workspace. Returns the created intent with its ID.

ParameterTypeDescription
title*stringShort name for the intent
objective*stringWhy this matters — the problem and who has it
productId*stringProduct (Space) ID this intent belongs to
outcomesstring[]Observable, testable state changes
constraintsstring[]Hard limits the implementation must respect
edgeCasesEdgeCase[]Failure modes with scenario and expectedBehavior
healthMetricsstring[]What to monitor after shipping
verificationobjectManual checks, unit tests, and e2e tests
problemSeverity"low" | "medium" | "high" | "critical"How severe the problem is

update_intent

Update an existing intent's content. Provide only the fields you want to change.

ParameterTypeDescription
intentId*stringThe intent ID to update
titlestringNew title
objectivestringUpdated objective
outcomesstring[]Replace all outcomes
constraintsstring[]Replace all constraints
edgeCasesEdgeCase[]Replace all edge cases
healthMetricsstring[]Replace all health metrics
verificationobjectReplace verification plan
problemSeverity"low" | "medium" | "high" | "critical"Updated severity

create_evidence

Create a new evidence item (bug, user feedback, observation, or feature request).

ParameterTypeDescription
content*stringThe evidence content — a finding, quote, or observation
type*"friction" | "quote" | "observation" | "metric" | "request"Type of evidence
productId*stringProduct ID this evidence belongs to
sourcestringWhere this evidence came from (e.g., "User interview")
sourceUrlstringURL to the original source
severity"low" | "medium" | "high" | "critical"Severity level (required for friction type)
sentiment"positive" | "negative" | "neutral" | "mixed"Emotional sentiment
tagsstring[]Category tags
stagestringUser journey stage (e.g., "Discovery", "Checkout")

link_evidence

Link or unlink evidence items to/from an intent for traceability.

ParameterTypeDescription
intentId*stringThe intent ID to link evidence to
linkstring[]Evidence IDs to link to this intent
unlinkstring[]Evidence IDs to unlink from this intent

verify_implementation

AI-grade your implementation against the intent spec. Returns pass/fail per item with reasoning and an overall score.

ParameterTypeDescription
intentId*stringThe intent ID to verify against
summary*stringDescription of what was implemented and how
codeChangesstringSummary of code changes (file list, key modifications)

Example: mark an intent as shipped after deployment

json
// Tool call: update_intent_status
{
  "intentId": "intent_abc123",
  "status": "shipped"
}

Zero-Config Tools

These tools work without an API key or Pathmode account. They save intent specs directly to your local file system as intent.md, .cursorrules, or CLAUDE.md.

intent_save

Save an intent spec to intent.md in the project root. Works without an API key — spec lives in your repo.

ParameterTypeDescription
spec*IntentSpecThe intent spec object (title, objective, outcomes, etc.)
pathstringFile path relative to cwd. Defaults to intent.md

intent_export

Export an intent spec as .cursorrules or CLAUDE.md section for AI agent consumption.

ParameterTypeDescription
format*"cursorrules" | "claude-md"Export format
spec*IntentSpecThe intent spec object
pathstringOutput file path. Defaults to .cursorrules or CLAUDE.md

Example: save a spec to your repo

json
// Tool call: intent_save
{
  "spec": {
    "title": "Improve checkout conversion",
    "objective": "Users abandon cart at payment step...",
    "outcomes": [
      "Payment form loads in under 500ms",
      "Error messages appear inline next to the field"
    ]
  },
  "path": "specs/checkout-conversion.md"
}

Prompts

Pre-built prompt templates that guide the AI through common workflows. Invoke these through your MCP client's prompt interface.

compile-intent

Socratic conversation to build a complete intent spec. Asks probing questions about objectives, outcomes, constraints, and edge cases. No API key needed.

implement-intent

Full implementation context for a specific intent. Pulls objective, outcomes, constraints, constitution rules, and linked evidence into a single prompt.

review-risks

Analyze the intent dependency graph for architectural risks. Identifies cycles, bottlenecks, orphaned intents, and stalled work.

what-next

Suggest the highest-priority intent to work on next based on dependency graph, status distribution, and evidence signals.

create-from-evidence

Search evidence items and create a new intent from observed patterns. Automatically anchors evidence to the resulting spec.

Example: start a spec-building conversation

bash
# In Claude Code, invoke the prompt directly:
/prompt compile-intent

# The AI will guide you through defining:
# - Objective (the problem and who has it)
# - Outcomes (observable, testable changes)
# - Constraints (hard limits)
# - Edge cases (failure modes)
# - Verification (how to confirm it works)

Resources

MCP resources expose live workspace data that AI clients can subscribe to. Resources update automatically as your workspace changes.

intent://current

Currently active intent — the first approved intent, or the most recently updated one.

intent://graph

Full dependency graph of all intents in the workspace with their relations.

intent://workspace-strategy

Workspace vision, architecture principles, non-negotiables, and constitution rules.

Data Models

TypeScript interfaces for the objects returned by the MCP tools and REST API. These are the shapes you will encounter when reading intents, evidence, and workspace data.

ApiIntent

The core intent spec. Represents a single unit of planned work with its objective, outcomes, constraints, edge cases, and verification plan. Intents move through a lifecycle: draft, validated, approved, shipped, verified.

typescript
interface ApiIntent {
  id: string;
  workspaceId: string;
  productId?: string;
  status: "draft" | "validated" | "approved" | "shipped" | "verified";
  version: number;
  title: string;
  objective: string;
  problemSeverity?: "low" | "medium" | "high" | "critical";
  outcomes: string[];
  constraints: string[];
  healthMetrics: string[];
  edgeCases: {
    id: string;
    scenario: string;
    expectedBehavior: string;
  }[];
  verification: {
    manualChecks?: string[];
    unitTests?: string[];
    e2eTests?: string[];
  };
  evidenceAnchors: Record<string, string[]>;
  evidenceIds: string[];
  relations: {
    targetId: string;
    type: string;
  }[];
  createdAt: string;
  updatedAt: string;
  shippedAt?: string;
  verifiedAt?: string;
}

ApiEvidence

An evidence item — a friction point, user quote, behavioral observation, metric, or feature request. Evidence is linked to products and can be anchored to specific parts of an intent spec.

typescript
interface ApiEvidence {
  id: string;
  productId: string;
  workspaceId: string;
  type: "friction" | "quote" | "observation" | "metric" | "request";
  content: string;
  source?: string;
  sourceUrl?: string;
  severity?: "low" | "medium" | "high" | "critical";
  sentiment?: "positive" | "negative" | "neutral" | "mixed";
  tags: string[];
  stage?: string;
  linkedIntentIds: string[];
  createdAt: string;
  updatedAt: string;
}

ApiWorkspace

The top-level workspace containing strategy (vision, trade-offs, architecture principles) and constitution rules that all implementations must respect.

typescript
interface ApiWorkspace {
  id: string;
  name: string;
  urlKey?: string;
  tags: string[];
  strategy: {
    vision?: string;
    tradeoffs?: string[];
    nonNegotiables?: string[];
    architecturePrinciples?: string[];
  } | null;
  constitutionRules: {
    id: string;
    category: string;
    text: string;
    isActive: boolean;
    createdAt: string;
  }[];
}

ApiVerificationResult

Returned by verify_implementation. Contains a pass/fail verdict, overall score (0-100), per-item results with reasoning, and a human-readable summary.

typescript
interface ApiVerificationResult {
  pass: boolean;
  score: number;
  results: {
    item: string;
    category: string;
    status: string;
    reasoning: string;
  }[];
  summary: string;
}

Key Field Reference

FieldModelNotes
evidenceAnchorsApiIntentMaps spec sections to evidence IDs. Keys: "objective", "outcome:0", "edgeCase:<uuid>", "constraint:0".
relationsApiIntentDependency links between intents. Types include depends_on, enables, and blocks.
constitutionRulesApiWorkspaceMandatory constraints checked during verification. Only active rules (isActive: true) are enforced.
statusApiIntentLifecycle: draft → validated → approved → shipped → verified. Each transition can trigger verification checklists.
scoreApiVerificationResult0-100. Based on how many outcomes, constraints, and constitution rules the implementation satisfies.

Use Cases

Common workflows that show how the MCP tools fit together in practice.

1. CI Verification

Use verify_implementation after deployment to check whether your code actually satisfies the intent spec. This closes the loop between what you planned and what you shipped — catching drift before it reaches users.

Step 1: Fetch the intent you are implementing

json
// Step 1: Fetch the intent spec your code implements
// Tool call: get_intent
{
  "intentId": "intent_abc123"
}

Step 2: Verify your implementation against the spec

json
// Step 2: After implementing, verify against the spec
// Tool call: verify_implementation
{
  "intentId": "intent_abc123",
  "summary": "Added inline validation to the payment form. Error messages now appear next to the invalid field within 100ms. Payment form lazy-loads and renders in under 400ms on 3G.",
  "codeChanges": "Modified: components/PaymentForm.tsx, lib/validation.ts, tests/payment.spec.ts"
}

Step 3: Mark as shipped if verification passes

json
// Step 3: If verification passes, mark as shipped
// Tool call: update_intent_status
{
  "intentId": "intent_abc123",
  "status": "shipped"
}

Step 4: Log implementation decisions

json
// Step 4: Log any implementation decisions for the record
// Tool call: log_implementation_note
{
  "intentId": "intent_abc123",
  "note": "Used Zod for inline validation instead of HTML5 constraint API — better error messages and consistent behavior across browsers."
}

Tip: In a CI pipeline, you can fail the build if verify_implementation returns pass: false or a score below your threshold. This prevents shipping code that doesn't match the agreed spec.

2. Evidence-Driven Specs

Start from real user problems instead of assumptions. Collect evidence first — friction points, user quotes, metrics — then create intents grounded in what you have observed. Linking evidence to intents creates traceability from user pain to shipped solution.

Step 1: Record evidence from user research

json
// Step 1: Record evidence from user research
// Tool call: create_evidence
{
  "content": "3 out of 5 users couldn't find the settings page. They expected it in the top nav, not buried in the profile dropdown.",
  "type": "friction",
  "productId": "prod_xyz",
  "source": "Usability test — March 2026",
  "severity": "high",
  "tags": ["navigation", "settings"],
  "stage": "Activation"
}

Step 2: Query for patterns across evidence

json
// Step 2: Query for patterns across evidence
// Tool call: query_evidence
{
  "productId": "prod_xyz",
  "type": "friction",
  "severity": "high",
  "search": "navigation"
}

Step 3: Create an intent informed by the evidence

json
// Step 3: Create an intent informed by the evidence
// Tool call: create_intent
{
  "title": "Surface settings in primary navigation",
  "objective": "Users cannot find settings because the link is hidden in the profile dropdown. 3 of 5 usability test participants failed this task.",
  "productId": "prod_xyz",
  "outcomes": [
    "Settings link appears in the top navigation bar on all viewport sizes",
    "Users can reach settings in one click from any page",
    "Usability test completion rate for 'change notification preferences' exceeds 90%"
  ],
  "constraints": [
    "Top nav must not exceed 5 primary items",
    "Mobile nav uses the same information architecture as desktop"
  ],
  "problemSeverity": "high"
}

Step 4: Link the evidence to the new intent

json
// Step 4: Link the evidence to the new intent
// Tool call: link_evidence
{
  "intentId": "intent_new456",
  "link": ["ev_001", "ev_002", "ev_003"]
}

Tip: Use the create-from-evidence prompt to automate this workflow. It searches your evidence, identifies patterns, and drafts an intent spec with evidence already linked.

3. Agent Context Injection

Feed your workspace strategy and intent specs into AI coding agents so they understand what to build and why. This ensures every AI-generated line of code is aligned with your product intent — not just technically correct, but solving the right problem.

Option A: Full workspace context as CLAUDE.md

json
// Option A: Export full workspace context as CLAUDE.md
// Tool call: export_context
{
  "format": "claude-md"
}

// This generates a CLAUDE.md section with:
// - Workspace strategy and vision
// - Constitution rules
// - Active intents and their statuses
// - Product context

Option B: Focused execution prompt for one intent

json
// Option B: Get a focused execution prompt for one intent
// Tool call: get_agent_prompt
{
  "intentId": "intent_abc123",
  "mode": "execute"
}

// Returns a structured prompt containing:
// - Objective and why it matters
// - Outcomes to achieve (testable criteria)
// - Constraints to respect
// - Edge cases to handle
// - Verification steps
// - Linked evidence for context

Option C: Export as .cursorrules for Cursor AI

json
// Option C: Export as .cursorrules for Cursor AI
// Tool call: export_context
{
  "format": "cursorrules",
  "intentId": "intent_abc123"
}

// Writes a .cursorrules file that Cursor reads automatically,
// injecting intent context into every AI interaction.

Option D: Local-only export (no API key needed)

json
// Option D: Use intent_export for local-only workflows
// Tool call: intent_export
{
  "format": "claude-md",
  "spec": {
    "title": "Improve checkout conversion",
    "objective": "Users abandon cart at payment step...",
    "outcomes": [
      "Payment form loads in under 500ms",
      "Error messages appear inline next to the field"
    ],
    "constraints": [
      "No third-party payment scripts on initial load"
    ]
  }
}

// Works without an API key — writes directly to your repo.

Tip: Combine get_agent_prompt with get_constitution to give your agent both the specific task and the global rules it must respect. Constitution rules act as guardrails that apply across all intents.

Error Handling

All API errors return JSON with an error field. HTTP status codes follow standard conventions.

StatusMeaningCommon Cause
400Bad RequestMissing required fields, invalid field values
401UnauthorizedMissing or invalid API key
403ForbiddenAPI key expired or insufficient scope
404Not FoundIntent or evidence ID does not exist
500Internal ErrorServer-side issue — retry or contact support
json
{
  "error": "Invalid or expired API key"
}

On this page

  • Getting Started
  • Authentication
  • REST API
    • Intents
    • Evidence
    • Workspace
    • Export
  • MCP Tools
    • Read Tools
    • Write Tools
    • Zero-Config
  • MCP Prompts
  • MCP Resources
  • Data Models
  • Use Cases
  • Error Handling
PathmodePathmode

The Intent Layer for Product Discovery.
Built with uncompromising focus for teams that ship.

Product

  • For Product Teams
  • Integrations
  • Claude Code
  • Cursor
  • Changelog

Resources

  • Blog
  • Playbook
  • Glossary
  • Pathmode vs. The Rest
  • Trust Center
  • Product Philosophy
  • About

Legal

  • Privacy Policy
  • Terms of Service

© 2026 Pathmode Oy (FI35979677). All rights reserved.

hello@pathmode.io