--- name: echowin-api description: Drafting, executing, and debugging RESTful API calls for the echowin AI phone agent platform. Manages agents, knowledgebases (webpages, documents, Q&A), contacts, tags, custom fields, and call logs via authenticated REST endpoints at https://echo.win/api/v1. Use when asked to interact with echowin services, query call data, update agent instructions, manage contacts, search knowledgebases, or look up platform documentation. version: 1.1.0 last_updated: 2026-02-24 --- # echowin API Skill ## Entry Point When this skill is activated, start by: 1. Confirming the user has an API key — if not, direct them to **Portal > Build > Integrations > API Keys Tab (https://echo.win/portal/integrations?tab=api-keys)** 2. Identifying the target resource (agents, knowledgebase, contacts, calls) 3. Discovering required IDs by listing resources if not already known 4. Executing the appropriate API call sequence from the actions below ## Capabilities This skill supports the following actions: | Action | Description | |--------|-------------| | `List_Agents` | Retrieve all AI phone agents for the account | | `Get_Agent_Instructions` | Read current agent prompt/instructions | | `Update_Agent_Instructions` | Modify agent behavior via instruction updates | | `Search_Knowledgebase` | Semantic search across agent knowledge sources (1 credit/search) | | `Manage_KB_Content` | CRUD on webpages, documents, and Q&A references | | `Refresh_Webpage` | Re-scrape a webpage source (rate limited to 1/day per page) | | `Manage_Contacts` | Create, read, update, delete contacts with tags and custom fields | | `Manage_Tags` | Create, update, delete tags for organizing contacts | | `Query_Calls` | List and filter call logs with transcripts and recordings | | `Get_Call_Details` | Retrieve full transcript, timeline, and metadata for a single call | ## When to Use Invoke this skill when the user asks to: - Manage their echowin AI agents or update agent instructions - Search or modify knowledgebase content - Work with contacts, tags, or custom fields - Access call logs and transcripts - Read how the platform works - Perform any echowin API operations ## Delegation Rules - **Do autonomously**: List resources, search knowledgebases, retrieve call logs, read agent instructions, fetch contact details - **Ask user first**: Before updating agent instructions, before deleting contacts, before any bulk operations - **Always confirm**: Any destructive operation (DELETE endpoints), instruction rewrites that significantly change agent behavior ## Step-by-Step Reasoning Before providing the final output, think step-by-step about these constraints: 1. Which resource am I targeting? (agent, knowledgebase, contact, call) 2. Do I have the required IDs? If not, list the resources first to discover them 3. Is this a read or write operation? Write operations need user confirmation 4. Am I within rate limits for this endpoint? 5. What is the expected response shape, and how should I present it to the user? ## Anti-Patterns - NEVER hardcode or guess API keys; always prompt the user for their key - NEVER call DELETE endpoints without explicit user confirmation - NEVER exceed rate limits; check `Retry-After` headers and wait accordingly - NEVER assume agent IDs or knowledgebase IDs; always list first to discover them - NEVER send instructions exceeding 100,000 characters - NEVER call webpage refresh more than once per 24 hours per webpage - NEVER make multiple write calls in rapid succession without checking for errors between them --- ## Authentication All requests require the `X-API-Key` header: ``` X-API-Key: {{API_KEY}} ``` Base URL: `https://echo.win/api/v1` If the API key is not provided, prompt the user: > "Please provide your echowin API key. You can find it in your echowin dashboard under **Settings > API**." ## Rate Limits Per-team rate limits by operation type: - **Standard** (GET): 100 requests/minute - **Search** (semantic search): 30 requests/minute - **Write** (POST/PUT/DELETE): 60 requests/minute - **Bulk** operations: 10 requests/minute - **Resource-specific** (e.g., webpage refresh): 1/day per resource Rate limited responses return 429 with `Retry-After` header and `retryAfter` in body. When rate limited, wait for the specified duration before retrying. --- ## Agents API Manage AI phone agents and their instructions. ### List Agents ``` GET /agents ``` Returns: `{ data: [{ id, name, description, knowledgebase: { id, name }, createdAt, updatedAt }] }` ### Get Agent Instructions ``` GET /agents/{{AGENT_ID}}/instructions ``` Returns: `{ data: { id, name, instructions, updatedAt } }` ### Update Agent Instructions ``` PUT /agents/{{AGENT_ID}}/instructions Body: { "instructions": "string (max 100,000 chars)" } ``` Returns: `{ data: { id, name, instructions, updatedAt }, message }` Note: Previous instructions saved to history (up to 20 versions). Full docs: https://echo.win/api-docs/agents --- ## Knowledgebase API Manage knowledge sources (webpages, documents, Q&A) that agents use for responses. ### Access Methods - Direct: `/knowledgebase/{{KNOWLEDGEBASE_ID}}/...` - Via Agent: `/agents/{{AGENT_ID}}/knowledgebase/...` (same endpoints, uses agent's assigned KB) ### Get Knowledgebase ``` GET /knowledgebase/{{KNOWLEDGEBASE_ID}} GET /agents/{{AGENT_ID}}/knowledgebase ``` Returns: `{ data: { id, name, description, webpages: [...], documents: [...], references: [...] } }` ### Search Knowledgebase (1 credit/search) ``` GET /knowledgebase/{{KNOWLEDGEBASE_ID}}/search?query={{SEARCH_QUERY}}&limit=10&threshold=0.1 GET /agents/{{AGENT_ID}}/knowledgebase/search?query={{SEARCH_QUERY}}&limit=10&threshold=0.1 ``` - query: required, max 2000 chars - limit: 1-50, default 10 - threshold: 0-1, default 0.1 (similarity cutoff) Returns: `{ data: [{ id, question, answer, similarity, type, source }], meta: { query, resultCount, creditsUsed: 1 } }` ### Webpages **Get webpage:** ``` GET /knowledgebase/{{KB_ID}}/webpages/{{WEBPAGE_ID}} ``` Returns: `{ data: { id, url, name, notes, lastScrapedAt, isUpdating, extractedContent: [...] } }` **Update webpage:** ``` PUT /knowledgebase/{{KB_ID}}/webpages/{{WEBPAGE_ID}} Body: { "name"?: "string", "url"?: "string", "notes"?: "string" } ``` **Refresh webpage (re-scrape, once per 24h):** ``` POST /knowledgebase/{{KB_ID}}/webpages/{{WEBPAGE_ID}}/refresh ``` Returns 429 if rate limited with `nextAvailableAt` timestamp. ### Documents **Get document:** ``` GET /knowledgebase/{{KB_ID}}/documents/{{DOCUMENT_ID}} ``` Returns: `{ data: { id, fileName, name, notes, isUpdating, extractedContent: [...] } }` **Update document:** ``` PUT /knowledgebase/{{KB_ID}}/documents/{{DOCUMENT_ID}} Body: { "name"?: "string", "notes"?: "string" } ``` ### Q&A References **Get reference:** ``` GET /knowledgebase/{{KB_ID}}/references/{{REFERENCE_ID}} ``` Returns: `{ data: { id, question, answer, type } }` **Update reference (auto-regenerates embedding):** ``` PUT /knowledgebase/{{KB_ID}}/references/{{REFERENCE_ID}} Body: { "question"?: "string", "answer"?: "string" } ``` Full docs: https://echo.win/api-docs/knowledgebase --- ## Contacts API Manage contacts with tags and custom fields. ### List Contacts ``` GET /contacts?page=1&limit=20&search={{SEARCH_TERM}}&tag={{TAG_ID}} ``` - page: 1-indexed - limit: max 100 - search: searches name, phone, email - tag: filter by tag ID Returns: `{ data: [...], pagination: { page, limit, totalCount, totalPages } }` ### Get Contact ``` GET /contacts/{{CONTACT_ID}} ``` Returns: `{ data: { id, name, phoneNumber, email, notes, tags, customFields, createdAt, updatedAt } }` ### Create Contact ``` POST /contacts Body: { "name": "required", "phoneNumber"?: "E.164 format", "email"?: "string", "notes"?: "string", "tagIds"?: ["uuid"], "customFields"?: {} } ``` ### Update Contact ``` PUT /contacts/{{CONTACT_ID}} Body: { "name"?, "phoneNumber"?, "email"?, "notes"?, "tagIds"?, "customFields"? } ``` ### Delete Contact ``` DELETE /contacts/{{CONTACT_ID}} ``` ### Tags ``` GET /tags # List all tags POST /tags { "name", "color"? } # Create tag PUT /tags/{{TAG_ID}} { "name"?, "color"? } # Update tag DELETE /tags/{{TAG_ID}} # Delete tag ``` ### Custom Fields ``` GET /custom-fields # List custom fields POST /custom-fields { "name", "fieldType": "text|number|select|date|boolean", "required"?, "options"? } ``` Full docs: https://echo.win/api-docs/contacts --- ## Calls API Access call logs with transcripts and recordings. ### List Calls ``` GET /calls?page=1&limit=20&search={{SEARCH_TERM}}&callType=all|incoming|outgoing&agentId={{AGENT_ID}}&minDuration=int&maxDuration=int&dateFrom=ISO&dateTo=ISO&sortBy=createdAt&sortOrder=desc ``` - limit: max 100 - search: searches phone numbers, transcripts, summaries Returns: `{ data: [{ id, from, to, type, status, duration, createdAt, endedAt, summary, score, agent, transcript, recordingUrl }], pagination }` ### Get Call Details ``` GET /calls/{{CALL_ID}} ``` Returns full call with transcript, activity timeline, recording URL, and metadata. Full docs: https://echo.win/api-docs/calls --- ## Rate Limits (Detailed) | Endpoint | Limit | | ------------------------ | --------------------------- | | List Agents | 1000/hour | | Agent Instructions | 100/hour | | Knowledgebase Get/Update | 100/hour | | Knowledgebase Search | 10,000/hour (1 credit each) | | Webpage Refresh | Once per 24h per webpage | | List Calls | 200/hour | | Call Details | 500/hour | | Contacts CRUD | 100-1000/hour | --- ## Error Handling ```json { "error": "Error message", "code"?: "ERROR_CODE" } ``` Common status codes and recovery actions: - **400**: Validation error (includes `details` array) — check request body against the endpoint schema above - **401**: Invalid/missing API key — prompt the user to verify their API key - **404**: Resource not found — verify the resource ID by listing resources first - **405**: Method not allowed — check the HTTP method is correct for the endpoint - **429**: Rate limit exceeded — read `Retry-After` header and wait before retrying - **500**: Server error — retry once after a brief delay; if persistent, inform the user If any required parameter is missing from the user's request (e.g., agent ID, contact name, search query), prompt the user for it before making the API call. Do not guess or fabricate IDs. --- ## Common Workflows ### Update agent knowledge 1. Get agent's knowledgebase: `GET /agents/{{AGENT_ID}}/knowledgebase` 2. Update Q&A: `PUT /agents/{{AGENT_ID}}/knowledgebase/references/{{REFERENCE_ID}}` 3. Or refresh webpage: `POST /agents/{{AGENT_ID}}/knowledgebase/webpages/{{WEBPAGE_ID}}/refresh` ### Search for information 1. Search KB: `GET /agents/{{AGENT_ID}}/knowledgebase/search?query={{SEARCH_QUERY}}` 2. Use results to answer or identify what to update ### Update agent behavior 1. Get current instructions: `GET /agents/{{AGENT_ID}}/instructions` 2. Modify and update: `PUT /agents/{{AGENT_ID}}/instructions` ### Analyze calls 1. List recent calls: `GET /calls?limit=10&sortBy=createdAt&sortOrder=desc` 2. Get details: `GET /calls/{{CALL_ID}}` for full transcript --- ## Output Templates When presenting API results to the user, use these structures for consistency: ### For list operations: ``` Found {{COUNT}} {{RESOURCE_TYPE}}: 1. **{{NAME}}** (ID: {{ID}}) — {{BRIEF_DESCRIPTION}} 2. ... ``` ### For single resource details: ``` **{{RESOURCE_TYPE}}: {{NAME}}** - ID: {{ID}} - {{KEY_FIELD}}: {{VALUE}} - Updated: {{UPDATED_AT}} ``` ### For write operations: ``` Successfully {{ACTION}} {{RESOURCE_TYPE}} "{{NAME}}" {{RELEVANT_DETAILS}} ``` --- ## Full Documentation - Platform Guide (How echowin works): https://echo.win/docs - Authentication: https://echo.win/api-docs/authentication - Agents: https://echo.win/api-docs/agents - Knowledgebase: https://echo.win/api-docs/knowledgebase - Contacts: https://echo.win/api-docs/contacts - Calls: https://echo.win/api-docs/calls - Agency: https://echo.win/api-docs/agency