API Documentation

Complete reference for the YodAI REST API. Create API keys in your dashboard Settings > API tab.

Install YodAI Desktop for Mac

Public download for Apple silicon Macs (M1 or newer). No API key or GitHub login is needed to download.

Download Mac installer · Installation instructions · Release metadata and checksum

Check the metadata for the current version and signing status. The pilot is unsigned and unnotarized; updates are installed manually.

Authentication

All API requests require a Bearer token

Authorization: Bearer ym_live_xxxxxxxxxxxxx

Quick Start

curl

curl -H "Authorization: Bearer ym_live_xxxxx" \
  https://yodai.app/api/v1/clients

JavaScript

const res = await fetch('https://yodai.app/api/v1/clients', {
  headers: { 'Authorization': 'Bearer ym_live_xxxxx' }
});
const { data } = await res.json();

Python

import requests
r = requests.get('https://yodai.app/api/v1/clients',
    headers={'Authorization': 'Bearer ym_live_xxxxx'})
data = r.json()['data']

Response Format

// Success
{ "data": { ... }, "meta": { "timestamp": "...", "request_id": "..." } }

// Paginated
{ "data": [...], "pagination": { "total": 50, "page": 1, "per_page": 20, "total_pages": 3 }, "meta": {...} }

// Error
{ "error": { "code": "VALIDATION_ERROR", "message": "..." }, "meta": {...} }

Rate Limits

Read operations: 100 req/min | Write operations: 30 req/min | AI operations: 10 req/min. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix seconds); 429 responses also carry Retry-After (seconds).

Commerce API examples

WooCommerce-first management, storefront and agent flows. Shopify and Stripe-native use the same normalized management contracts where the provider supports them.

Keep the two credentials separate

Management endpoints under /api/v1 require a scoped ym_live_ agency API key. Published storefront endpoints under /api/site-commerce require only the short-lived published-site capability delivered with that site. Never put an agency API key, provider credential or connector secret in browser code.

Configure WooCommerce hosted handoff, validate readiness, then queue an idempotent catalogue sync.

curl -X PUT https://yodai.app/api/v1/sites/SITE_ID/commerce \
  -H "Authorization: Bearer ym_live_xxxxx" -H "Content-Type: application/json" \
  -d '{"provider":"woocommerce","checkoutStrategy":"woo_hosted_handoff","integrationId":"33333333-3333-4333-8333-333333333333","catalogueSource":"hybrid","defaultCurrency":"NZD","enabled":true}'

curl -X POST https://yodai.app/api/v1/sites/SITE_ID/commerce/test \
  -H "Authorization: Bearer ym_live_xxxxx"

curl -X POST https://yodai.app/api/v1/sites/SITE_ID/commerce/sync \
  -H "Authorization: Bearer ym_live_xxxxx" -H "Content-Type: application/json" \
  -d '{"resource":"catalogue","reason":"Initial WooCommerce import","idempotencyKey":"agent-run-00000001"}'

# Poll sanitized integration, webhook, sync, connector and job status.
curl -H "Authorization: Bearer ym_live_xxxxx" \
  https://yodai.app/api/v1/integrations/INTEGRATION_ID/commerce/status

Management rate limits: reads 100/min, writes 30/min, AI 10/min per API key.

Storefront rates are separately enforced per published capability, trusted IP and cart capability; inspect its OpenAPI extensions for exact limits.

Handle 409 as an idempotency/configuration conflict, 422 as validation or unsupported capability, 429 using Retry-After, and 503 as a temporary provider degradation.

MCP Server (AI Agent Integration)

Connect AI agents to YodAI using the Model Context Protocol. Choose between a hosted HTTP endpoint or a local stdio server.

Hosted MCP Endpoint

Connect any MCP-compatible client to YodAI over HTTP using the Streamable HTTP transport. No local setup required.

POST https://yodai.app/api/mcp

Authentication uses the same Bearer token as the REST API. The endpoint is stateless — each request is independent with no session management.

tools/list returns the complete catalogue by default. When server-side paging is enabled the response includes a nextCursor; repeat tools/list with that cursor until it is absent. Neither the JavaScript nor the Python MCP SDK pages automatically, so follow the cursor yourself as shown below.

Client Configuration

Claude Desktop / Claude Code

// .mcp.json or claude_desktop_config.json
{
  "mcpServers": {
    "yodai": {
      "type": "url",
      "url": "https://yodai.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ym_live_xxxxx"
      }
    }
  }
}

curl (raw MCP protocol)

# One request — returns the whole catalogue unless paging is enabled
curl -X POST https://yodai.app/api/mcp \
  -H "Authorization: Bearer ym_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Forward-compatible: page until nextCursor is absent (needs jq)
cursor=''
while :; do
  params='{}'; [ -n "$cursor" ] && params='{"cursor":"'"$cursor"'"}'
  page=$(curl -s -X POST https://yodai.app/api/mcp \
    -H "Authorization: Bearer ym_live_xxxxx" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":'"$params"'}')
  echo "$page" | jq -r '.result.tools[].name'
  cursor=$(echo "$page" | jq -r '.result.nextCursor // empty')
  [ -z "$cursor" ] && break
done

JavaScript (MCP SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://yodai.app/api/mcp"),
  { requestInit: { headers: { "Authorization": "Bearer ym_live_xxxxx" } } }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// listTools() does not auto-paginate — follow nextCursor until it is absent
const tools = [];
let cursor;
do {
  const page = await client.listTools(cursor ? { cursor } : {});
  tools.push(...page.tools);
  cursor = page.nextCursor;
} while (cursor);

const result = await client.callTool({ name: "list_clients", arguments: {} });

Python (MCP SDK)

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://yodai.app/api/mcp",
    headers={"Authorization": "Bearer ym_live_xxxxx"}
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # list_tools() does not auto-paginate — follow nextCursor until absent
        tools = []
        cursor = None
        while True:
            page = await session.list_tools(cursor=cursor)
            tools.extend(page.tools)
            cursor = page.nextCursor
            if not cursor:
                break

        result = await session.call_tool("list_clients", {})

Rate limits: 100 requests/min per API key. Individual tool calls that hit the REST API internally are subject to their own per-endpoint rate limits (read: 100/min, write: 30/min, AI: 10/min).

Both transports expose the same complete tool registry for use with Claude, ChatGPT, and other AI agents.

Chatbot lead destination tools:

list_chatbot_lead_destinations, set_chatbot_lead_destinations, create_chatbot_lead_destination, update_chatbot_lead_destination, delete_chatbot_lead_destination, test_chatbot_lead_destination, list_chatbot_leads, get_chatbot_lead, update_chatbot_lead_status, list_chatbot_lead_deliveries, retry_chatbot_lead_delivery

Chatbot configuration tools:

list_client_chatbots, create_client_chatbot, get_client_chatbot, update_client_chatbot, configure_client_chatbot, update_client_chatbot_brain, configure_client_chatbot_voice, configure_client_chatbot_lead_capture, set_client_chatbot_active, regenerate_client_chatbot_key, delete_client_chatbot, list_client_knowledge_sources

Knowledge Bank tools (agency + client + facets):

list_agency_knowledge_sources, get_agency_knowledge_source, create_agency_knowledge_source, update_agency_knowledge_source, delete_agency_knowledge_source, reindex_agency_knowledge_source, get_agency_knowledge_source_clients, set_agency_knowledge_source_clients, list_agency_knowledge_folders, create_agency_knowledge_folder, update_agency_knowledge_folder, delete_agency_knowledge_folder, list_client_knowledge_sources, create_client_knowledge_source, get_client_knowledge_source, update_client_knowledge_source, delete_client_knowledge_source, reindex_client_knowledge_source, list_knowledge_facets, get_knowledge_facet, delete_knowledge_facet, merge_knowledge_facet, delete_knowledge_facet_value, merge_knowledge_facet_value

Memory security and temporal-chat tools:

list_agent_memories, get_agent_memory, list_memory_security_incidents, get_memory_security_incident, preview_memory_lifecycle_operation, execute_memory_lifecycle_operation, review_client_knowledge_source, get_chatbot_chat_session_config, update_chatbot_chat_session_config, get_agent_chat_session_config, update_agent_chat_session_config, list_chatbot_chat_sessions, get_chatbot_chat_session, list_agent_chat_sessions, get_agent_chat_session

Agent voice tools:

get_agent_voice_options, create_agent_voice_session, execute_agent_voice_tool_call, persist_agent_voice_transcript

Coupon tools:

list_coupon_offers, get_coupon_offer, create_coupon_offer, update_coupon_offer, delete_coupon_offer, generate_coupon_code, list_coupon_codes, get_coupon_code, revoke_coupon_code, delete_coupon_code, update_coupon_code, set_coupon_code_enabled

Image Tool MCP tools (generation is generate_image; image + folder CRUD live in the generated-media / media tools):

generate_image, get_image_tool_settings, update_image_tool_settings, get_image_branding_context, remove_image_background, autocrop_image, decompose_image_layers, ai_edit_image, apply_image_border, strip_image_metadata, list_image_studio_documents, get_image_studio_document, delete_image_studio_document, list_media_folders, create_media_folder, update_media_folder, delete_media_folder, reorder_media_folders

AI Agent Reference (SKILL.md)

Comprehensive skill reference for AI agents — includes MCP tool references, typed task workflows, and key concepts

The SKILL.md follows Anthropic's agent skill standard and provides AI agents with structured documentation for the entire YodAI API surface. It includes complete tool references, step-by-step workflows, and important behavioral notes.

View SKILL.md Download

Fetch via curl:

curl https://yodai.app/api/v1/skill-reference -o SKILL.md

Task boards and coding briefs

Board settings uses default_task_type (general or coding). New tasks inherit it when task_type is omitted. Changing board type leaves existing tasks unchanged. The task editor can convert a task separately.

Within a Coding task, coding_task_type selects the category below. The editor autosaves after a short pause and flushes on close. API and MCP clients read coding details first, then send expected_version (0 for a new brief). Omitted fields are retained; type_details replaces the whole object, so merge inactive fields before writing. Each brief value is optional text up to 4,000 characters.

Coding categories and type_details keys
Category / API value	Brief fields (type_details)
New feature `new_feature`	`feature_problem`: Problem and user goal `feature_users`: Users and workflow `feature_requirements`: Functional requirements `feature_integrations`: Data and integrations `feature_rollout`: Rollout and success measures
Bug `bug`	`bug_expected`: Expected behaviour `bug_actual`: Actual behaviour `bug_environment`: Affected versions and environment `bug_impact`: Frequency and impact `bug_evidence`: Diagnostic evidence
Update Feature `update_feature`	`update_current`: Current feature behaviour `update_proposed`: Requested changes `update_reason`: Reason for the update `update_compatibility`: Compatibility and migration `update_regression`: Regression coverage and rollout
Design Change `design_change`	`design_scope`: Screens and components `design_references`: Design references `design_behaviour`: Layout and interactions `design_states`: Responsive layouts and states `design_accessibility`: Accessibility and visual checks
Other `other`	`other_objective`: Objective and context `other_scope`: Work scope `other_output`: Expected output `other_validation`: Verification approach
Planning `planning`	`planning_question`: Goal or decision to resolve `planning_context`: Current state and assumptions `planning_options`: Options to evaluate `planning_risks`: Dependencies and risks `planning_output`: Plan format and level of detail
Testing `testing`	`testing_target`: Test target and scope `testing_approach`: Test approach `testing_scenarios`: Scenarios and expected results `testing_setup`: Test environment and data `testing_evidence`: Pass criteria and evidence
Deployment `deployment`	`deployment_release`: Release and target `deployment_prechecks`: Pre-deployment checks `deployment_rollout`: Rollout steps and window `deployment_health`: Health checks and abort criteria `deployment_rollback`: Rollback and recovery
Security `security`	`security_finding`: Finding or threat `security_impact`: Severity and impact `security_scope`: Authorised assessment scope `security_remediation`: Remediation requirements `security_verification`: Verification and evidence
Sys Admin `sys_admin`	`admin_systems`: Systems and desired state `admin_change`: Change procedure and dependencies `admin_impact`: Impact and maintenance window `admin_recovery`: Backup and recovery `admin_validation`: Post-change verification

Shared fields include repository/environment, base branch, responsible person/reviewer, acceptance criteria, constraints, paths, reproduction steps, priority, start/deadline, deliverable/completion policy, budget and attempts. The interactive OpenAPI schema lists their exact types and limits. The Bug category uses the shared reproduction_steps field.

MCP: use create_board_label/update_board_label for board type, create_card/update_card for task type, and get_coding_details/update_coding_details for coding briefs. Saving a brief never starts a run. Starting execution and human review use separate scoped operations below.

Clients

Manage your agency's client accounts

GET/api/v1/clients

List all clients

Scopes:

clients:read

Query params: page, per_page

POST/api/v1/clients

Create a new client

Scopes:

clients:write

{ "name": "Acme Corp", "website": "https://acme.com", "persona": "B2B SaaS company" }

GET/api/v1/clients/:id

Get client details

Scopes:

clients:read

PATCH/api/v1/clients/:id

Update client

Scopes:

clients:write

{ "name": "New Name" }

DELETE/api/v1/clients/:id

Archive client

Scopes:

clients:write