Mypa

MyPA Skill

MyPA is a voice-first personal communication hub. Every message is a Tez (short for Tezit) — a discrete, actionable item with its full context iceberg preserved forever. This skill lets you send messages to teammates, manage your tez feed, get briefings, interrogate context, and share mirrors.

Quick Start for External OpenClaw

This skill works with any OpenClaw runtime, not just the MyPA Canvas UI.

1. Install

cp SKILL.md ~/.openclaw/workspace/skills/mypa/SKILL.md

2. Set Environment

export MYPA_API_URL="https://api.mypa.chat"   # or your instance URL
export MYPA_EMAIL="you@example.com"
export MYPA_PASSWORD="your-password"
# Optional: for PA-to-PA messaging
export RELAY_URL="https://relay.tezit.com"     # or your relay URL

3. Verify

# Login
TOKEN=$(curl -s -X POST "$MYPA_API_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"$MYPA_EMAIL\",\"password\":\"$MYPA_PASSWORD\"}" | jq -r '.data.tokens.accessToken')

# Bootstrap — discover teams, capabilities, endpoints
curl -s "$MYPA_API_URL/api/auth/bootstrap" -H "Authorization: Bearer $TOKEN" | jq .

If you see data.user and data.teams in the response, you're connected.

Bootstrap Flow (CRITICAL for External Runtimes)

On first contact with a MyPA instance, always run the bootstrap sequence:

1. Login → POST /api/auth/login → store accessToken + refreshToken
2. Bootstrap → GET /api/auth/bootstrap → discover:
   • teams[] — all teams the user belongs to
   • capabilities — which integrations are available (relay, crm, paWorkspace, federation, scheduler)
   • instanceMode — "team" or "personal"
   • connectedHubs — (personal mode only) federated team hubs
   • endpoints — backend URL, relay URL, cross-team URL
3. If teams.length > 1 → present the list and ask the user which team to scope to
4. If teams.length === 1 → set scope automatically
5. Store the resolved team scope in conversation memory for subsequent operations

curl "$MYPA_API_URL/api/auth/bootstrap" \
  -H "Authorization: Bearer $TOKEN"

Response shape:

{
  "data": {
    "user": { "id": "uuid", "email": "...", "name": "...", "department": "...", "teamId": "uuid" },
    "teams": [{ "id": "uuid", "name": "Alpha Team", "role": "member", "isActive": true, "memberCount": 4 }],
    "instanceMode": "team",
    "capabilities": { "relay": true, "crm": false, "paWorkspace": false, "federation": true, "scheduler": false },
    "connectedHubs": [],
    "endpoints": { "backend": "https://api.mypa.chat", "relay": "http://10.108.0.2:3002", "crossTeam": null }
  }
}

Multi-Team Scope Resolution (CRITICAL)

Users may belong to multiple teams. Write operations must be scoped to a specific team.

Rules

• Read operations (context, briefing, feed, library search): use the user's active team by default. In personal mode, can aggregate across all teams.
• Write operations (create team card, classify, relay share): MUST have an explicit teamId when the user belongs to 2+ teams.
• Disambiguation protocol: if teams.length > 1 and no teamId is specified, the backend returns AMBIGUOUS_TEAM_SCOPE with the list of teams. Present this to the user and ask them to choose.

Handling AMBIGUOUS_TEAM_SCOPE

If a write operation returns HTTP 400 with error.code === "AMBIGUOUS_TEAM_SCOPE":

{
  "error": {
    "code": "AMBIGUOUS_TEAM_SCOPE",
    "message": "User is a member of multiple teams. Specify teamId explicitly.",
    "teams": [
      { "id": "team-1-uuid", "name": "Alpha Team", "role": "member" },
      { "id": "team-2-uuid", "name": "Beta Team", "role": "admin" }
    ]
  }
}

Agent response: Present the team list and ask the user which team they mean. Then retry the operation with the selected teamId.

Scope Modes

• team:{teamId} — scoped to a specific team (default for write operations)
• personal — local data only (user's personal tezits, no team context)
• all-teams — read-only aggregation across all connected teams (personal instance mode only, via cross-team endpoints)

Authentication

All requests require a JWT Bearer token. Obtain one by logging in.

Login:

curl -X POST "$MYPA_API_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "'"$MYPA_EMAIL"'", "password": "'"$MYPA_PASSWORD"'"}'

Store accessToken and refreshToken from the response. Include on every request:

Authorization: Bearer $TOKEN

Access tokens expire after 15 minutes. On 401, refresh:

curl -X POST "$MYPA_API_URL/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "'"$REFRESH_TOKEN"'"}'

Optional CRM Environment

If Twenty CRM is configured for this deployment, set:

export TWENTY_API_URL="http://localhost:3000"
export TWENTY_API_KEY="your_twenty_api_key"

Use CRM calls only when both are present. If missing, continue with MyPA-only workflows.

Optional PA Workspace bridge for Google execution flows:

export PA_WORKSPACE_API_URL="http://localhost:3003"

When set, CRM orchestration can optionally execute PA email/calendar actions in addition to Tez draft generation.

CRM + Tez Operations

IMPORTANT: Before any CRM operation, check CRM status first. If configured: true and reachable: true, proceed with CRM calls. If not, inform the user that CRM is not yet set up.

CRM Intent Routing (CRITICAL)

Treat CRM as an API integration (Twenty), not a local workspace file.

When a user asks things like:

• "add this person to CRM"
• "update that deal"
• "show my contacts/opportunities/tasks"

You MUST:

1. Call GET /api/crm/status first.
2. If data.configured === true and data.reachable === true, execute CRM API calls (/api/crm/people, /api/crm/opportunities, /api/crm/tasks).
3. If not configured/reachable, tell the user CRM integration is not configured or unreachable and ask for setup help (URL/key), not for a file path.

You MUST NOT:

• ask the user for a "CRM file", "CRM folder", or local CRM path as the primary approach.
• claim CRM is unavailable just because no local file exists.

Example user request:

"Add my wife, Natalie Williams to our CRM."

Expected action flow:

1. GET /api/crm/status
2. If healthy, POST /api/crm/people with structured name:

curl -X POST "$MYPA_API_URL/api/crm/people" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"name":{"firstName":"Natalie","lastName":"Williams"}}}'

3. Confirm creation result to user.

Check CRM + runtime status

curl "$MYPA_API_URL/api/crm/status" \
  -H "Authorization: Bearer $TOKEN"

curl "$MYPA_API_URL/api/crm/workflows/status" \
  -H "Authorization: Bearer $TOKEN"

List CRM entities

curl "$MYPA_API_URL/api/crm/people?limit=20" \
  -H "Authorization: Bearer $TOKEN"

curl "$MYPA_API_URL/api/crm/opportunities?limit=20" \
  -H "Authorization: Bearer $TOKEN"

curl "$MYPA_API_URL/api/crm/tasks?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Write CRM entities (create/update)

Create a person — name is a structured {firstName, lastName} object. Use emails.primaryEmail for email.

curl -X POST "$MYPA_API_URL/api/crm/people" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"name":{"firstName":"Jane","lastName":"Example"},"emails":{"primaryEmail":"jane@example.com"},"jobTitle":"VP Sales","city":"New York","phones":{"primaryPhoneNumber":"+15551234567"}}}'

Update a person — PATCH with only the fields to change:

curl -X PATCH "$MYPA_API_URL/api/crm/people/<entity-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"jobTitle":"CTO","city":"San Francisco"}}'

Update a task:

curl -X PATCH "$MYPA_API_URL/api/crm/tasks/<task-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"status":"in_progress"}}'

Build Tez-ready context from CRM

curl -X POST "$MYPA_API_URL/api/crm/tez-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"opportunity","entityId":"<id>"}'

Use data.relayContext with relay /tez/share or /conversations/:id/messages.

Cross-system coordination workflow

curl -X POST "$MYPA_API_URL/api/crm/workflows/coordinate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType":"opportunity",
    "entityId":"<id>",
    "objective":"Move deal to next stage with clear owner actions",
    "tez":{"teamId":"<team-id>","recipients":["<user-id>"]},
    "openclaw":{"enabled":true},
    "googleWorkspace":{"enabled":true,"dryRun":true}
  }'

This returns:

• tezDraft (ready for relay /tez/share)
• openclaw planning summary
• googleWorkspace draft/execute result (dry-run by default)

Key Concepts

Tez-Based Model: Everything is a tez. Tezits are discrete, actionable items — not threads.

Personal vs Team Tezits:

• "Message for Me" → personal tez (private note, reminder). Only the creator sees it.
• "Message for Team" → team tez sent to specific recipients or all team members.

Library of Context: ALL original content (voice transcripts, typed text) is preserved forever. Context is sacred — never suggest deleting it.

Status State Machine:

pending → active → resolved → archived

archived is terminal. Transitions are enforced by the API.

Sending Messages (CRITICAL)

Step 0: Resolve Team Scope

Before any write operation, ensure you have a resolved team scope:

• If user is in 1 team → scope is set automatically (no teamId needed)
• If user is in 2+ teams → you MUST include teamId in write requests
• If unsure, check teams[] from the bootstrap response

Step 1: Classify Intent

ALWAYS classify first before creating a tez. This determines whether the message is for the user themselves, a specific teammate, or the whole team.

For multi-team users, pass teamId to scope name matching to the correct team:

curl -X POST "$MYPA_API_URL/api/cards/classify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Tell Ros I love her", "teamId": "team-uuid"}'

Response:

{
  "data": {
    "intent": "dm",
    "recipientId": "f23cdac6-...",
    "recipientName": "Rosalind Price",
    "confidence": 98,
    "reason": "First name match \"Rosalind Price\" with directive"
  },
  "meta": { "teamSize": 3 }
}

Intent values:

• "self" → Create a personal tez (POST /api/cards/personal)
• "dm" → Create a team tez directed to the specific recipient
• "broadcast" → Create a team tez for all team members (set shareToTeam: true)

Step 2: Check Auto-Send Preference

After classifying, check the user's paPreferences.autoSendDMs setting (available in the PA context). The rules:

• If autoSendDMs is true, confidence is ≥ 90, intent is "dm", and team size is ≤ 10: send immediately without confirmation.
• Otherwise: show the user who you're sending to and ask for confirmation before creating the tez.

Step 3: Create the Tez

Personal Tez (intent: "self"):

curl -X POST "$MYPA_API_URL/api/cards/personal" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Remember to buy milk", "summary": "Buy milk"}'

Team Tez (intent: "dm" or "broadcast"):

curl -X POST "$MYPA_API_URL/api/cards/team" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I love you!",
    "summary": "Love note to Ros",
    "recipients": ["f23cdac6-..."],
    "teamId": "team-uuid"
  }'

Team broadcast (intent: "broadcast"):

curl -X POST "$MYPA_API_URL/api/cards/team" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Reminder: standup is at 10am today.",
    "summary": "Standup @ 10am",
    "shareToTeam": true,
    "teamId": "team-uuid"
  }'

Parameters:

• content (string, required) — The message content
• summary (string, optional) — Short summary; fallback to truncated content
• recipients (string[], optional) — Targeted message to specific teammates
• shareToTeam (boolean, optional) — Explicit team-wide broadcast. If true, server expands recipients to all teammates.
• teamId (string, optional) — Required for multi-team users. Single-team users can omit.
• dueDate (string, optional) — ISO 8601 datetime

Rule: For team cards, you must provide either recipients[] or shareToTeam: true (no silent broadcast).

IMPORTANT: Treat Tez as the canonical system of record. External channels (WhatsApp/Telegram/email/etc) are optional and depend on configured relay channel providers. If not configured, deliver via Tez (team cards or relay) and share mirrors when needed.

Search & Feed

Feed (Primary View)

curl "$MYPA_API_URL/api/cards/feed?sort=priority&status=pending&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

• sort — priority (default) or chronological
• status — pending, active, resolved, archived, or all
• limit — Max 50 (default 20)
• cursor — For pagination

Library Search

Search all preserved original content.

curl "$MYPA_API_URL/api/library/search?q=dinner+plans" \
  -H "Authorization: Bearer $TOKEN"

Tez Details & Actions

Get Details

curl "$MYPA_API_URL/api/cards/:id" \
  -H "Authorization: Bearer $TOKEN"

Change Status

curl -X PATCH "$MYPA_API_URL/api/cards/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Valid transitions: pending→active, pending→resolved, pending→archived, active→resolved, active→archived, resolved→archived.

Respond to a Tez

curl -X POST "$MYPA_API_URL/api/cards/:id/respond" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "On it!"}'

Snooze

curl -X POST "$MYPA_API_URL/api/cards/:id/snooze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"until": "2026-02-08T09:00:00Z"}'

Archive

curl -X DELETE "$MYPA_API_URL/api/cards/:id" \
  -H "Authorization: Bearer $TOKEN"

PA Context (ALWAYS FETCH FIRST)

Before answering any question about the user's messages, team, or workload, ALWAYS fetch context first.

curl "$MYPA_API_URL/api/pa/context" \
  -H "Authorization: Bearer $TOKEN"

Response includes:

• userName — The user's name
• teamName — Active team name
• teamMembers — Array of { id, name, roles, skills, department } — these are the people the user can message
• pendingCardCount — Number of pending tezits
• topPriorityCard — Most recent pending tez
• recentCards — Last 30 days of tezits with status and response counts
• paPreferences — User's PA settings including autoSendDMs, model, tone, responseStyle
• teams — All teams the user belongs to

Multi-team note: The teams array shows ALL teams the user belongs to. teamMembers shows members of the active team only. For multi-team users, the user may need to switch active team scope before operations.

CRITICAL: The teamMembers array tells you who the user can send messages to. When the user says "tell Ros...", match "Ros" against teamMembers[].name. Use the classify endpoint for reliable matching.

Briefing

curl "$MYPA_API_URL/api/pa/briefing" \
  -H "Authorization: Bearer $TOKEN"

Returns: pendingCount, activeCount, resolvedToday, topPriorityCards, staleCards, upcomingDeadlines.

Tez Mirror (External Sharing)

Generate a lossy, read-only summary of a tez for sharing outside the app (SMS, email, clipboard).

Render Preview

curl -X POST "$MYPA_API_URL/api/tez/:cardId/mirror" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "surface"}'

Templates:

• "teaser" (~50 chars) — Push notification / SMS preview
• "surface" (~200 chars) — Email / group chat sharing
• "surface_facts" (~500 chars) — Sharing with someone who needs context

Log Share (Audit)

curl -X POST "$MYPA_API_URL/api/tez/:cardId/mirror/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "surface", "destination": "sms"}'

Tezit Protocol

Interrogate a Tez

Ask questions answered strictly from the tez's transmitted context.

curl -X POST "$MYPA_API_URL/api/tez/:cardId/interrogate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "What was decided about dinner?"}'

Get Citations

curl "$MYPA_API_URL/api/tez/:cardId/citations" \
  -H "Authorization: Bearer $TOKEN"

Export as Tezit Bundle

curl "$MYPA_API_URL/api/tez/:cardId/export" \
  -H "Authorization: Bearer $TOKEN"

Export as Portable Tez Bundle (Level 2)

Portable bundles are designed to be moved between systems (export/import, backups, external sharing).

curl "$MYPA_API_URL/api/tez/:cardId/export/portable" \
  -H "Authorization: Bearer $TOKEN"

Fork a Tez (Counter-Argument)

curl -X POST "$MYPA_API_URL/api/tez/:cardId/fork" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forkType": "counter", "content": "Actually, I think..."}'

Fork types: counter, extension, reframe, update.

Web Research Pattern (Browser → Tez)

When the user asks you to research something on the web:

1. Ask whether this should be a private note or a team share (and who the recipients are).
2. Use your browser tool to gather sources. Capture at least: title, url, and accessedAt date.
3. Produce a short surface summary the user can act on.
4. Preserve the full context iceberg as Tez context (facts + artifacts + constraints).

Share research as a personal Tez (private, preserved in Library)

Use contextLayers to preserve the research notes and sources alongside the Tez.

curl -X POST "$MYPA_API_URL/api/cards/personal" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Research summary: competitor pricing tiers and key differentiators",
    "summary": "Competitor pricing research",
    "contextLayers": [
      {
        "type": "assistant",
        "query": "Research competitor pricing and summarize with sources",
        "content": "Findings:\\n- Tier A: ...\\n- Tier B: ...\\n\\nSources (accessed 2026-02-10):\\n- Example Pricing Page: https://example.com/pricing\\n- Example Docs: https://example.com/docs"
      }
    ]
  }'

Share research as a relay Tez (DM or team-visible)

Use relay context[] for structured layers (background, fact, artifact, constraint, etc). Put sources in artifact layers and set confidence/source for facts.

curl -X POST "$RELAY_URL/tez/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team-uuid",
    "visibility": "team",
    "surfaceText": "Competitor X pricing: 3 tiers; biggest gap is seat-based minimums.",
    "type": "update",
    "urgency": "normal",
    "recipients": [],
    "context": [
      { "layer": "background", "content": "Goal: compare pricing + packaging vs our current plan." },
      { "layer": "fact", "content": "Tier 1 starts at $Y/month (seat-based).", "confidence": 90, "source": "verified" },
      { "layer": "constraint", "content": "Numbers may change; verify before sending externally." },
      { "layer": "artifact", "content": "Source: Competitor pricing page (accessed 2026-02-10) https://example.com/pricing" }
    ]
  }'

Tez Sharing (External Access via Share Tokens)

Share tokens grant scoped, read-only guest access to interrogate a specific Tez's context. The sender controls what's visible, how many interrogations are allowed, and can revoke at any time.

Create a Share Token

curl -X POST "$MYPA_API_URL/api/tez/:cardId/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "For Alice",
    "contextScope": "surface",
    "maxInterrogations": 10,
    "expiresInHours": 48
  }'

Context scope options:

• "surface" — Card content + summary only. TIP answers from surface text alone.
• "full" — All context items visible. Full interrogation capability.
• "selected" — Only specific context items (pass contextItemIds array).

Response:

{
  "data": {
    "token": "raw-token-shown-once",
    "shareUrl": "https://mypa.chat/tez/abc123?token=...",
    "tokenId": "uuid",
    "expiresAt": "2026-02-11T10:00:00Z"
  }
}

IMPORTANT: The raw token is shown ONLY once. Store or share it immediately.

List Share Tokens

curl "$MYPA_API_URL/api/tez/:cardId/shares" \
  -H "Authorization: Bearer $TOKEN"

Returns all tokens for the card (without raw token values). Use to manage active shares.

Update Scope (Share More / Pull Back)

curl -X PATCH "$MYPA_API_URL/api/tez/:cardId/share/:tokenId" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contextScope": "full"}'

This is the mechanism for sharing more context or pulling it back. Change contextScope, add/remove contextItemIds, or adjust maxInterrogations.

Revoke a Share Token

curl -X DELETE "$MYPA_API_URL/api/tez/:cardId/share/:tokenId" \
  -H "Authorization: Bearer $TOKEN"

Immediately revokes the token. Any future use returns 401.

Tezit Relay (PA-to-PA Messaging)

When the Tezit channel plugin is active, the agent can send and receive native Tez messages through the relay. The relay URL is available as $RELAY_URL when configured.

Multi-team note: The teamId in relay calls must match the user's resolved team scope. For multi-team users, always pass the explicit teamId from the bootstrap/scope resolution step.

Send a Tez via Relay

curl -X POST "$RELAY_URL/tez/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team-uuid",
    "surfaceText": "The budget decision: approved $50k for Q2",
    "type": "decision",
    "urgency": "high",
    "recipients": ["recipient-uuid"],
    "context": [
      {"layer": "background", "content": "Q2 planning concluded last week"},
      {"layer": "fact", "content": "$50,000 approved for marketing spend", "confidence": 100, "source": "stated"}
    ]
  }'

Check Relay Unread

curl "$RELAY_URL/unread" \
  -H "Authorization: Bearer $TOKEN"

Conversations (DM + Group)

Use conversations when the user wants a familiar chat experience (WhatsApp/Slack-style) rather than discrete Tez broadcasts.

Create a DM (exactly 2 people total):

curl -X POST "$RELAY_URL/conversations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"dm","memberIds":["other-user-uuid"]}'

Create a group (2+ people total, requires name):

curl -X POST "$RELAY_URL/conversations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"group","name":"Project Alpha","memberIds":["user-a-uuid","user-b-uuid"]}'

List my conversations:

curl "$RELAY_URL/conversations" \
  -H "Authorization: Bearer $TOKEN"

Send a message in a conversation:

curl -X POST "$RELAY_URL/conversations/<conversation-id>/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "surfaceText":"Quick update: shipped the fix, waiting on CI.",
    "type":"update",
    "urgency":"normal",
    "context":[
      {"layer":"background","content":"Bug was in invite accept upsert."},
      {"layer":"artifact","content":"PR: https://github.com/org/repo/pull/123"}
    ]
  }'

Mark conversation read:

curl -X POST "$RELAY_URL/conversations/<conversation-id>/read" \
  -H "Authorization: Bearer $TOKEN"

Register Contact with Channel Routing

curl -X POST "$RELAY_URL/contacts/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Alice Smith",
    "email": "alice@example.com",
    "phone": "+1234567890",
    "preferredChannel": "whatsapp",
    "channels": ["tezit", "whatsapp", "email"]
  }'

Channel routing fields:

• channels — Ordered fallback chain. First reachable channel wins. e.g. ["tezit", "email", "whatsapp"]
• preferredChannel — Explicit override. If set, always try this first.
• phone — Phone number for SMS/WhatsApp/Telegram delivery.
• telegramId — Telegram user ID for Telegram delivery.

Routing logic (for agent):

1. Check preferredChannel — if set and available, use it.
2. Otherwise, iterate channels array in order. First channel the recipient is reachable on wins.
3. If recipient has OpenClaw (tezit channel available) → native Tez (full context iceberg preserved).
4. If fallback to lossy channel (WhatsApp, email, etc.) → generate mirror + TIP interrogation link.

Mirror Settings

Get Settings

curl "$MYPA_API_URL/api/settings/mirror" \
  -H "Authorization: Bearer $TOKEN"

Update Settings

curl -X PATCH "$MYPA_API_URL/api/settings/mirror" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mirrorWarningsEnabled": false}'

Twenty CRM + Tez Workflows (When Configured)

Check CRM connectivity

curl "$MYPA_API_URL/api/crm/status" \
  -H "Authorization: Bearer $TOKEN"

If data.configured and data.reachable are both true, CRM operations are available.

Pull CRM object context and share as Tez

1. Fetch CRM object data from MyPA's CRM adapter:

curl "$MYPA_API_URL/api/crm/people?limit=5" \
  -H "Authorization: Bearer $TOKEN"

2. Build Tez-ready context from a CRM object:

curl -X POST "$MYPA_API_URL/api/crm/tez-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"opportunity","entityId":"opp_123"}'

3. Send a team Tez with the returned contextLayers attached:

curl -X POST "$MYPA_API_URL/api/cards/team" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Handoff: priority follow-up for key account",
    "summary": "CRM follow-up handoff",
    "shareIntent": "handoff",
    "contextLayers": [
      {
        "type": "text",
        "content": "CRM opportunity snapshot: opportunity_id=opp_123, title=Renewal Q2, stage=negotiation, next_step=Call by Friday",
        "query": "Explain blockers and next actions for recipient PA"
      }
    ]
  }'

Daily CRM + Tez briefing pattern

1. Pull urgent CRM items (tasks/opportunities due soon).
2. Create one personal tez (/api/cards/personal) summarizing top priorities.
3. Create team handoff tezits for delegated items (shareIntent: "handoff").
4. Use /api/tez/:cardId/interrogate to answer recipient follow-up questions using attached context only.

Response Format

Success: { "data": { ... }, "meta": { "total": 42 } } Error: { "error": { "code": "...", "message": "..." } } Status codes: 200, 201, 400, 401, 403, 404, 429

API Contract Examples

The following endpoints have frozen contracts. Breaking changes will break OpenClaw integration.

GET /api/pa/context

Request:

GET /api/pa/context HTTP/1.1
Authorization: Bearer <jwt-token>

Response (200 OK):

{
  "data": {
    "userId": "uuid",
    "userName": "Alice Smith",
    "teamId": "uuid",
    "teamName": "Smith Family",
    "userRoles": ["engineer", "team_lead"],
    "teams": [
      {
        "id": "uuid",
        "name": "Smith Family",
        "role": "member",
        "isActive": true,
        "memberCount": 4
      }
    ],
    "pendingCardCount": 3,
    "topPriorityCard": {
      "id": "uuid",
      "summary": "Dinner plans tonight",
      "dueDate": "2026-02-08T18:00:00Z",
      "responseCount": 2
    },
    "recentCards": [
      {
        "id": "uuid",
        "summary": "Team meeting notes",
        "status": "resolved",
        "dueDate": null,
        "createdAt": "2026-02-07T10:00:00Z",
        "responseCount": 5,
        "responsePreviews": ["Great points!", "Agreed on timeline"]
      }
    ],
    "teamMembers": [
      {
        "id": "uuid",
        "name": "Bob Smith",
        "roles": ["engineer"],
        "skills": ["python", "docker"],
        "department": "Engineering"
      }
    ],
    "integrations": {
      "openclawConfigured": true,
      "twentyConfigured": true,
      "notificationsEnabled": true
    },
    "paPreferences": {
      "autoSendDMs": true,
      "model": "gpt-4",
      "tone": "warm"
    }
  }
}

GET /api/pa/briefing

Request:

GET /api/pa/briefing HTTP/1.1
Authorization: Bearer <jwt-token>

Response (200 OK):

{
  "data": {
    "pendingCount": 3,
    "activeCount": 2,
    "resolvedToday": 5,
    "topPriorityCards": [
      {
        "id": "uuid",
        "content": "Review Q1 budget",
        "summary": "Budget review",
        "status": "pending",
        "dueDate": "2026-02-09T17:00:00Z",
        "createdAt": "2026-02-08T09:00:00Z",
        "updatedAt": "2026-02-08T09:00:00Z"
      }
    ],
    "staleCards": [],
    "upcomingDeadlines": [
      {
        "id": "uuid",
        "content": "Submit expense report",
        "summary": "Expenses",
        "status": "pending",
        "dueDate": "2026-02-10T23:59:00Z",
        "createdAt": "2026-02-05T14:00:00Z",
        "updatedAt": "2026-02-05T14:00:00Z"
      }
    ]
  }
}

POST /api/cards/classify

Request:

POST /api/cards/classify HTTP/1.1
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "content": "Tell Ros I'll be home at 6pm"
}

Response (200 OK):

{
  "data": {
    "intent": "dm",
    "recipientId": "f23cdac6-...",
    "recipientName": "Rosalind Price",
    "confidence": 98,
    "reason": "First name match \"Rosalind Price\" with directive"
  },
  "meta": {
    "teamSize": 3
  }
}

POST /api/cards/personal

Request:

POST /api/cards/personal HTTP/1.1
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "content": "Remember to buy milk",
  "summary": "Buy milk",
  "sourceType": "text",
  "dueDate": "2026-02-09T12:00:00Z"
}

Response (201 Created):

{
  "card": {
    "id": "uuid",
    "content": "Remember to buy milk",
    "summary": "Buy milk",
    "fromUserId": "uuid",
    "status": "pending",
    "sourceType": "text",
    "dueDate": "2026-02-09T12:00:00Z",
    "createdAt": "2026-02-08T10:30:00Z",
    "updatedAt": "2026-02-08T10:30:00Z"
  }
}

POST /api/cards/team

Request:

POST /api/cards/team HTTP/1.1
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "content": "I'll be home at 6pm",
  "summary": "Home at 6",
  "sourceType": "text",
  "recipients": ["f23cdac6-..."]
}

Response (201 Created):

{
  "card": {
    "id": "uuid",
    "content": "I'll be home at 6pm",
    "summary": "Home at 6",
    "fromUserId": "uuid",
    "status": "pending",
    "sourceType": "text",
    "createdAt": "2026-02-08T10:35:00Z",
    "updatedAt": "2026-02-08T10:35:00Z"
  }
}

GET /api/cards/feed

Request:

GET /api/cards/feed?status=pending&limit=10 HTTP/1.1
Authorization: Bearer <jwt-token>

Response (200 OK):

{
  "cards": [
    {
      "id": "uuid",
      "content": "Review project proposal",
      "summary": "Project review",
      "fromUserId": "uuid",
      "status": "pending",
      "createdAt": "2026-02-08T09:00:00Z",
      "updatedAt": "2026-02-08T09:00:00Z"
    }
  ],
  "meta": {
    "hasMore": false,
    "cursor": null
  }
}

POST /api/tez/:cardId/interrogate

Request:

POST /api/tez/abc-123/interrogate HTTP/1.1
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "question": "What was decided about dinner?",
  "sessionId": "session-uuid"
}

Response (200 OK):

{
  "data": {
    "answer": "Based on the transmitted context, dinner was decided for 6:30pm at the Italian restaurant downtown.",
    "classification": "answerable",
    "confidence": "high",
    "contextScope": "full",
    "citations": [
      {
        "contextItemId": "ctx-uuid",
        "excerpt": "Let's do 6:30pm at Luigi's downtown",
        "claim": "Dinner time and location were decided"
      }
    ]
  }
}

GET /api/library/search

Request:

GET /api/library/search?q=dinner+plans&limit=10 HTTP/1.1
Authorization: Bearer <jwt-token>

Response (200 OK):

{
  "results": [
    {
      "cardId": "uuid",
      "contextId": "ctx-uuid",
      "content": "Let's plan dinner for Friday night at the new restaurant",
      "snippet": "...plan <b>dinner</b> for Friday night...",
      "rank": 2.45,
      "createdAt": "2026-02-05T14:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "query": "dinner plans"
  }
}

Discovery (Public)

No auth required — these power the Tez social network.

Trending tezits:

GET {MYPA_API_URL}/api/discover/trending?limit=10&period=7d

Returns highest-engagement tezits from the last 7 days. Response:

{
  "data": [
    { "cardId": "uuid", "summary": "...", "senderName": "Alice", "engagementScore": 47, "interrogationCount": 8, "citationCount": 5, "createdAt": "..." }
  ]
}

Platform stats:

GET {MYPA_API_URL}/api/discover/stats

Returns: { totalTezits, totalInterrogations, totalCitations, activeUsers, topContributors: [{name, tezCount, engagementScore}] }

User profile:

GET {MYPA_API_URL}/api/discover/profile/{userId}

Returns: { displayName, memberSince, tezCount, totalEngagement, topTezits: [{cardId, summary, score}] }

Share with TIP link (agent convenience):

POST {MYPA_API_URL}/api/tez/{cardId}/share-with-link
Authorization: Bearer <jwt-token>
Content-Type: application/json

{ "contextScope": "full", "maxInterrogations": 100, "expiresInHours": 168 }

Creates a share token and returns full shareable URLs. Used when routing a Tez to a lossy channel (WhatsApp, email, etc.) — include the interrogateUrl so the recipient can interrogate the full context.

Error Response Format

All errors follow this structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "content",
      "issue": "Required field missing"
    }
  }
}

Common error codes:

• UNAUTHORIZED (401) - Missing or invalid auth token
• FORBIDDEN (403) - No access to resource
• NOT_FOUND (404) - Resource doesn't exist
• VALIDATION_ERROR (400) - Invalid request data
• AMBIGUOUS_TEAM_SCOPE (400) - Multi-team user must specify teamId (includes teams[] in error)
• NOT_TEAM_MEMBER (403) - User is not a member of the specified team
• INTERNAL_ERROR (500) - Server error

Tez Transport (Email Delivery via PA)

Send Tez via email from your PA's Google Workspace account. The recipient gets:

• Rich HTML email with Tez content
• .tez.json attachment (full bundle for import)
• TIP interrogation link (ask questions about the transmitted context)

Requirements:

• PA Workspace must be configured on the server
• User must have a provisioned PA (Google Workspace account)

Send Tez via Email

curl -X POST "$MYPA_API_URL/api/tez-transport/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPaEmail": "alice-pa@mypa.chat",
    "toEmail": "bob@example.com",
    "tezId": "card-uuid",
    "subject": "Optional subject override"
  }'

Parameters:

• fromPaEmail — Your PA's email (e.g., robertsonprice-pa@mypa.chat)
• toEmail — Recipient's email address
• tezId — Card ID to send (fetches bundle from backend)
• bundle — OR provide a full Tez bundle directly (skip tezId if providing this)
• subject — Optional email subject (defaults to Tez summary)

Response (200 OK):

{
  "data": {
    "messageId": "google-message-id",
    "fromPaEmail": "alice-pa@mypa.chat",
    "toEmail": "bob@example.com",
    "subject": "Project Update",
    "sentAt": "2026-02-10T01:00:00Z"
  }
}

When to use:

• Sending Tez to someone without MyPA (external recipient)
• Email is their preferred channel
• You want full context preservation via email (not just lossy text)

Email contents:

• HTML body with Tez surface text + context summary
• X-Tezit-Protocol: 1.2 header (Tez-aware email clients can parse)
• .tez.json attachment (full bundle for import/archival)
• TIP link (recipient can interrogate without MyPA account)

Get Email Send History

curl "$MYPA_API_URL/api/tez-transport/log?userId=user-uuid&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Returns recent email sends from the user's PA.

Inbound Tez Bridge (Channel Messages → Relay)

When you receive a message from an external channel (WhatsApp, Telegram, email, SMS, etc.), always record it as a Tez in the relay. This ensures the PA's eyes are on every message and the Library of Context captures everything.

Recording an Inbound Channel Message

curl -X POST "$RELAY_URL/tez/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team-uuid",
    "surfaceText": "Message content from the channel",
    "type": "note",
    "sourceChannel": "whatsapp",
    "sourceAddress": "+1234567890",
    "context": [
      {"layer": "background", "content": "Received via WhatsApp from +1234567890 at 2026-02-09T10:30:00Z"}
    ]
  }'

Required fields for bridge:

• sourceChannel — The originating channel: "whatsapp", "telegram", "email", "sms", "imessage", etc.
• sourceAddress — The sender's address on that channel (phone number, email, etc.)
• context — At minimum, a "background" layer noting the source channel and timestamp.

When to bridge:

• Every inbound message on a non-Tez channel should be recorded
• Include the original sender identity in sourceAddress
• If the message has attachments or rich content, add them as "artifact" context layers
• If you can infer the sender's name, add a "relationship" context layer

Guidelines for the Agent

1. Sending messages = creating tezits. When the user says "send a message to Ros" or "tell Tom about dinner", classify the intent first, then create a team tez. There is NO external messaging system — tezits ARE messages.

2. ALWAYS classify before sending. Use POST /api/cards/classify to determine intent and recipient. Never guess who a message is for — the classify endpoint matches names against the team directory.

3. Fetch PA context first. Before answering workload questions or sending messages, call GET /api/pa/context to know who's on the team and what's pending.

4. Check autoSendDMs. If the user's paPreferences.autoSendDMs is true and the classify result has ≥90 confidence for a DM in a small team (≤10), send without asking. Otherwise confirm the recipient first.

5. Context is sacred. Never suggest deleting context. Only archiving.

6. Voice-first awareness. Users may be dictating. Interpret intent generously through transcription artifacts.

7. **B

…(truncated)