# MyApi — AI Agent Instructions

> IMPORTANT: You MUST ask the human user for explicit approval before performing ANY action.
> Describe what you intend to do and wait for the user to confirm before proceeding.
> Never call endpoints, reveal tokens, or execute services without the user saying "yes".
> This rule applies to every single request — no exceptions.

## About
MyApi is a personal API platform. It gives you access to the owner's knowledge base,
connected services, vault tokens, personas, and identity — but only with their permission.

## Canonical Base URL
Always use: https://www.myapiai.com
⚠️ IMPORTANT: Do NOT append /api/v1 to this base URL.
   All endpoint paths listed below already include /api/v1.
   Correct: https://www.myapiai.com/api/v1/skills
   Wrong:   https://www.myapiai.com/api/v1/api/v1/skills  ← double-prefix bug
Do NOT follow HTTP redirects — redirects from the bare domain strip the Authorization header
and will cause all authenticated requests to fail with "Invalid or revoked token".

## Authentication
- Use the Authorization header: Bearer <token>
- Or the query parameter: ?token=<token>

## If Your Token Is Missing or Rejected — Handshake Flow
No username or extra info needed. Just two steps:

1. POST https://www.myapiai.com/api/v1/handshakes  (no auth required)
   Body: { "agentId": "<your-unique-id>", "requestedScopes": ["read"], "message": "<who you are>" }
   Allowed scopes: read, professional, availability
   → You receive a handshakeId.

2. Poll GET https://www.myapiai.com/api/v1/handshakes/<handshakeId>/status  (no auth required)
   → Returns { status: "pending" | "approved" | "denied" }
   → When approved, the owner will share a new token with you. Use it as your Bearer token.

3. Resume with your new token.

## Getting Started (With a Token)
1. STOP and ask the user for approval before doing anything.
2. Authenticate with the provided token using https://www.myapiai.com as the base URL.
3. Call GET /api/v1/tokens/me/capabilities to see what you can do.
4. Before each subsequent action, describe your intent and wait for user approval.

## Approval Rules
- READ operations (GET): Ask the user before fetching any data.
- WRITE operations (POST/PUT/DELETE): Always require explicit approval with a clear description of what will change.
- Token reveal (GET /api/v1/vault/tokens/:id/reveal): Always ask before revealing secrets.
- Service execution (POST /api/v1/services/:name/execute): Always describe the action and wait for approval.
- Never chain multiple actions without checking in with the user between each one.

## Key Endpoints
All paths are relative to https://www.myapiai.com — do NOT add /api/v1 to the base URL.

### Start Here
- GET  /api/v1/gateway/context                    → Full AI context in one call (persona, identity, memory, endpoints)
- GET  /api/v1/quick-start                        → Step-by-step guide (includes handshake flow)
- GET  /api/v1/auth/me                            → Verify token and see your token metadata
- GET  /api/v1/users/me                           → Owner identity (name, role, bio, timezone)

### Discovery
- GET  /api/v1/                                  → API root and endpoint discovery
- GET  /api/v1/capabilities                       → Scope-aware capability list
- GET  /api/v1/tokens/me/capabilities             → Your token's permissions
- GET  /openapi.json                              → Full OpenAPI specification

### Memory & Knowledge
- GET    /api/v1/memory                           → List persistent memory entries
- POST   /api/v1/memory                           → Store a memory entry  { content: "..." }
- PATCH  /api/v1/memory/:id                       → Update a memory entry
- DELETE /api/v1/memory/:id                       → Delete one memory entry
- GET    /api/v1/brain/knowledge-base             → List knowledge base documents
- POST   /api/v1/brain/knowledge-base/upsert      → Create or update a KB doc by title
- GET    /api/v1/brain/knowledge-base/:id         → Get full content of a KB document

### Skills
- GET  /api/v1/skills                             → List skills (scope: skills:read). Filter: ?slug=&category=&q=&limit=
- GET  /api/v1/skills/suggestions?q=              → Fuzzy skill suggestions for AI discovery (no ID needed)
- GET  /api/v1/skills/_by_slug/:slug              → Fetch skill by name/slug (preferred for AI agents)
- GET  /api/v1/skills/_batch?slug=&id=            → Fetch multiple skills in one request (repeatable params)
- GET  /api/v1/skills/:id                         → Get skill details + versions + forks
- GET  /api/v1/skills/:id/content                 → Get raw SKILL.md content (JSON or Accept: text/markdown)
- GET  /api/v1/skills/:id/skill.md                → Get SKILL.md as raw text/markdown
- PUT  /api/v1/skills/:id/skill.md                → Set SKILL.md content (YAML frontmatter auto-sanitized)
- POST /api/v1/skills                             → Create skill (scope: skills:write)
- PUT  /api/v1/skills/:id                         → Update skill (scope: skills:write)
- DELETE /api/v1/skills/:id                       → Delete skill (scope: skills:write)

### Personas
- GET  /api/v1/personas                           → List AI personas
- GET  /api/v1/personas/:id                       → Get a specific persona

### Identity & Preferences
- GET  /api/v1/identity                           → Owner basic identity
- GET  /api/v1/identity/professional              → Professional identity
- GET  /api/v1/identity/availability              → Availability and timezone

### Services & Vault
- GET  /api/v1/vault/tokens                       → Connected service tokens (vault)
- GET  /api/v1/services                           → List ALL services with status (native + Composio-backed)
- GET  /api/v1/services/:name/methods             → Documented operations for a service + generic proxy usage
- POST /api/v1/services/:name/proxy               → Proxy raw API request to a service  { path, method, body?, query? }
- POST /api/v1/services/:name/execute             → Execute a predefined service method  { method, params }
- GET  /api/v1/services/google/gmail/messages     → List Gmail messages
- GET  /api/v1/services/google/drive/files        → List Google Drive files
- POST /api/v1/services/google/drive/upload       → Upload file to Google Drive

### Composio-Connected Services (clean names like gmail, slack, notion)
Services connected through Composio appear in GET /api/v1/services under their clean
toolkit name (e.g. gmail, notion, linkedin) — no special prefix.
Call them EXACTLY like native services — same proxy endpoint, same auth, same scopes:
  POST /api/v1/services/{toolkit}/proxy
  Body: { "path": "<provider-native REST path>", "method": "GET|POST|PUT|PATCH|DELETE", "body": {...}, "query": {...} }
Example — list Gmail messages through Composio:
  POST /api/v1/services/gmail/proxy
  Body: { "path": "/gmail/v1/users/me/messages", "method": "GET", "query": { "maxResults": 5 } }
MyApi relays the call via Composio with the stored credentials — you never see provider tokens.
Discover what is connected via GET /api/v1/services (status: "connected") and per-service call
documentation via GET /api/v1/services/{toolkit}/methods.

### Service Token Scopes
- services:read / services:write                  → global access to all connected services (write implies read)
- services:{name}:read|write|*                    → STANDALONE per-service grant (works without the global scope),
                                                    e.g. services:gmail:read. Write implies read.
- A 403 with "Requires 'services:...' scope" means the token lacks the scope above — ask the
  owner to issue a token with it from /dashboard/access-tokens.

### Access Requests (no auth required)
- POST /api/v1/handshakes                         → Request access (no auth)
- GET  /api/v1/handshakes/:id/status              → Poll handshake status (no auth)

## AFP — PC File System Access (master token only)
Requires a registered AFP daemon running on the target PC.
- GET  /api/v1/afp/devices                        → List registered PCs and their online status
- GET  /api/v1/afp/:deviceId/ls?path=<dir>        → List directory contents on the PC
- GET  /api/v1/afp/:deviceId/read?path=<file>     → Read a file from the PC
- POST /api/v1/afp/:deviceId/write                → Write a file to the PC  { path, content, encoding? }
- GET  /api/v1/afp/:deviceId/stat?path=<path>     → File/directory metadata
- POST /api/v1/afp/:deviceId/exec                 → Run a shell command on the PC  { cmd, cwd?, timeout? }
- DELETE /api/v1/afp/:deviceId/rm                 → Delete a file or directory  { path, recursive? }
- POST /api/v1/afp/:deviceId/mkdir                → Create a directory  { path }
- GET  /api/v1/afp/download/:platform             → Download AFP daemon binary (linux|mac|mac-arm|win) — no auth required

## Automations (Scheduled, Proactive Tasks — Pro/Heavy plan)
Schedule recurring or one-time tasks that MyApi runs on its own, even when no agent is connected.
- GET    /api/v1/triggers                          → List the owner's automations
- POST   /api/v1/triggers                          → Create one. Recommended shape:
    { "name": "Morning digest", "kind": "schedule",
      "schedule": { "type": "daily", "atHour": 7, "atMinute": 0 }, "timezone": "UTC",
      "actionType": "ai_prompt",
      "action": { "prompt": "Summarize my unread email and send it to me", "services": ["gmail"] } }
  schedule.type ∈ once | interval | daily | weekly | monthly.
  actionType ∈ ai_prompt (an AI agent acts over the owner's CONNECTED services — recommended) |
              service_proxy { service, path, method, body } | afp_exec { deviceId, cmd }.
  ai_prompt emails through the owner's own connected mailbox (e.g. Gmail), never a system mailer.
- POST   /api/v1/triggers/:id/run                  → Run an automation now (test)
- GET    /api/v1/triggers/:id/runs                 → Run history
- PATCH/DELETE /api/v1/triggers/:id                → Edit / delete
- GET    /api/v1/triggers/ai/settings              → AI providers/models + MyApi-AI credit wallet (balance, limit, auto-reload)
Automation activity counts against the plan's API-call quota. MyApi-provided AI is metered as
credits (1 credit = $0.01); using your own provider key (keyMode:"byo") is free.

## Memory (Cross-AI Persistent Context)
Store notes that persist across all AI sessions. Any AI reading gateway/context sees these.
- GET    /api/v1/memory                           → List all memory entries (id, content, created_at)
- POST   /api/v1/memory  { content: "..." }       → Store a new memory (markdown text)
- PATCH  /api/v1/memory/:id  { content: "..." }   → Update a memory entry
- DELETE /api/v1/memory/:id                       → Delete one memory entry
- DELETE /api/v1/memory                           → Clear all memories

## Documentation
- OpenAPI spec: https://www.myapiai.com/openapi.json
- Quick start: https://www.myapiai.com/api/v1/quick-start
- AI plugin manifest: https://www.myapiai.com/.well-known/ai-plugin.json