Referencia de la API

Página generada automáticamente del OpenAPI (https://api.pymaia.com/api/openapi.json). No la edites a mano: corré npm run gen:api en docs-site/.

Todos los endpoints son POST https://api.pymaia.com/api/v1/{tool} con Authorization: Bearer pymaia_... y body JSON. La respuesta es { ok, result, duration_ms }. Ver Primeros pasos y Errores.

162 endpoints en 21 áreas.

Account

get_ai_usage

Get AI usage (message count, tokens, cost USD) for the org in a given month. Defaults to the current month.

• Endpoint: POST /api/v1/get_ai_usage
• Scopes: billing:read
• Parámetros: month

get_credit_balance

Get current credit balance + plan + monthly grant + next reset.

• Endpoint: POST /api/v1/get_credit_balance
• Scopes: billing:read
• Parámetros: ninguno

list_ai_usage_history

Time-series of AI usage per month for the org.

• Endpoint: POST /api/v1/list_ai_usage_history
• Scopes: billing:read
• Parámetros: limit

list_credit_packs

List credit packs available for purchase (name, credits, price_usd).

• Endpoint: POST /api/v1/list_credit_packs
• Scopes: billing:read
• Parámetros: ninguno

list_feedback

List feedback submitted for agent task runs

• Endpoint: POST /api/v1/list_feedback
• Scopes: agents:read
• Parámetros: agent_slug, min_rating, max_rating, limit

submit_feedback

Submit feedback (rating/correction) on an agent task run

• Endpoint: POST /api/v1/submit_feedback
• Scopes: agents:run
• Parámetros: run_id, rating, correction, tags (*obligatorio)

Ads

list_google_ad_groups

List Google Ads ad groups with performance. Filter by campaign_id to drill down the hierarchy (campaign → ad group → ad).

• Endpoint: POST /api/v1/list_google_ad_groups
• Scopes: ads:read
• Parámetros: campaign_id, date_from, date_to, limit

list_google_ads_ads

List individual Google Ads ads (headline, description, ad_type) with performance. Use ad_group_id for hierarchy drill-down.

• Endpoint: POST /api/v1/list_google_ads_ads
• Scopes: ads:read
• Parámetros: ad_group_id, campaign_id, date_from, date_to, limit

propose_campaign

Propose a COMPLETE advertising campaign (campaign → ad set/group → creative → ad) for Meta, Google or TikTok. Builds an Action Bundle queued for human approval (creating real ads ALWAYS needs explicit human sign-off; the campaign is created PAUSED). Provide a resolved spec — for Meta: creative.imageHash + creative.pageId; for Google: headlines/descriptions/keywords; for TikTok: identity + creatives. Returns a bundleId the user approves in the Pymaia dashboard.

• Endpoint: POST /api/v1/propose_campaign
• Scopes: actions:approve
• Parámetros: platform, spec, brief_text, estimated_reach, declared_categories (*obligatorio)

propose_pause_campaign

Propose pausing an ad campaign. Creates a pending agent_action that must be approved via approve_action. Supported platforms: meta, google, tiktok.

• Endpoint: POST /api/v1/propose_pause_campaign
• Scopes: ads:write
• Parámetros: platform, campaign_id, reason* (*obligatorio)

propose_update_budget

Propose updating daily budget on an ad campaign. Creates a pending agent_action for approval. Platforms: meta, google, tiktok.

• Endpoint: POST /api/v1/propose_update_budget
• Scopes: ads:write
• Parámetros: platform, campaign_id, new_daily_budget, currency, reason (*obligatorio)

query_email_campaigns

Query email marketing campaigns with open/click rates

• Endpoint: POST /api/v1/query_email_campaigns
• Scopes: crm:read
• Parámetros: limit

query_google_campaigns

Query Google Ads campaign performance data with cost, conversions_value and per-row ROAS.

• Endpoint: POST /api/v1/query_google_campaigns
• Scopes: ads:read
• Parámetros: date_from, date_to, limit

query_meta_campaigns

Query Meta Ads campaign performance data with spend, impressions, clicks, conversions, conversion_value and per-row ROAS.

• Endpoint: POST /api/v1/query_meta_campaigns
• Scopes: ads:read
• Parámetros: date_from, date_to, limit

query_meta_creatives

Query Meta ad creatives with fatigue scores and thumbnails. Useful for spotting creative fatigue and identifying top performers.

• Endpoint: POST /api/v1/query_meta_creatives
• Scopes: ads:read
• Parámetros: date_from, date_to, min_fatigue_score, limit

query_tiktok_campaigns

Query TikTok Ads campaign performance (impressions, clicks, spend, conversions) for the org ad accounts.

• Endpoint: POST /api/v1/query_tiktok_campaigns
• Scopes: ads:read
• Módulo: requiere module_tiktok_ads habilitado (si está apagado → 404).
• Parámetros: date_from, date_to, limit

Agents

delete_agent_memory

Delete an agent memory by ID

• Endpoint: POST /api/v1/delete_agent_memory
• Scopes: memory:write
• Parámetros: memory_id* (*obligatorio)

get_skill_content

Get the full content of a skill by slug

• Endpoint: POST /api/v1/get_skill_content
• Scopes: skills:read
• Parámetros: slug* (*obligatorio)

list_agents

List all available AI agents with their capabilities and tools

• Endpoint: POST /api/v1/list_agents
• Scopes: agents:read
• Parámetros: ninguno

list_skills

List all AI skills (knowledge/frameworks) available to agents

• Endpoint: POST /api/v1/list_skills
• Scopes: skills:read
• Parámetros: category

read_agent_memories

Read accumulated agent memories/insights for this organization. Memories contain patterns, anomalies, and learnings from previous analyses.

• Endpoint: POST /api/v1/read_agent_memories
• Scopes: memory:read
• Parámetros: agent_slug, memory_type, path_prefix, min_importance, limit

run_agent

Run an AI agent with a specific task. The agent has access to marketing data tools and will analyze/respond based on its specialization.

• Endpoint: POST /api/v1/run_agent
• Scopes: agents:run
• Parámetros: agent_slug, message (*obligatorio)

write_agent_memory

Write or update an agent memory. Use paths like “meta/campaigns/roas-pattern” to organize knowledge hierarchically.

• Endpoint: POST /api/v1/write_agent_memory
• Scopes: memory:write
• Parámetros: agent_slug, path, content*, memory_type, importance, ttl_days (*obligatorio)

Analytics

get_pixel_scan

Get the last pixel/tracking scan for the org website (Meta Pixel, GA4, GTM, Google Ads, TikTok Pixel, Hotjar, Clarity detection). Stored under organizations.settings.pixel_scan.

• Endpoint: POST /api/v1/get_pixel_scan
• Scopes: analytics:read
• Parámetros: ninguno

get_site_analytics

Métricas del sitio hosteado del cliente: visitas y leads (total y últimos 30 días) + tasa de conversión.

• Endpoint: POST /api/v1/get_site_analytics
• Scopes: workspace:read
• Parámetros: ninguno

query_analytics

Query Google Analytics sessions, users, conversions and revenue per day.

• Endpoint: POST /api/v1/query_analytics
• Scopes: analytics:read
• Parámetros: date_from, date_to, limit

query_pagespeed_scores

Query PageSpeed Insights scores (performance, LCP, FID, CLS, TTFB) by URL and device. Latest scans first.

• Endpoint: POST /api/v1/query_pagespeed_scores
• Scopes: analytics:read
• Parámetros: url, device, limit

query_search_console

Query Google Search Console data - queries, clicks, impressions, CTR, position

• Endpoint: POST /api/v1/query_search_console
• Scopes: analytics:read
• Parámetros: date_from, date_to, limit

run_pagespeed_scan

Trigger a PageSpeed Insights scan for a URL via pagespeed-scan edge function.

• Endpoint: POST /api/v1/run_pagespeed_scan
• Scopes: analytics:read
• Parámetros: url*, device (*obligatorio)

run_pixel_scan

Scan the org website for tracking pixels and tags (Meta, GA4, GTM, Google Ads, TikTok, Hotjar, Clarity). Calls pixel-scanner edge function and stores result in org settings.

• Endpoint: POST /api/v1/run_pixel_scan
• Scopes: analytics:read
• Parámetros: ninguno

Automation

create_alert_rule

Create an alert rule. When the metric breaches the threshold, a notification fires via the configured channels.

• Endpoint: POST /api/v1/create_alert_rule
• Scopes: notifications:write
• Parámetros: name, description, platform, metric, condition, threshold*, comparison_period, channels (*obligatorio)

create_webhook

Create an outbound webhook that receives POST with HMAC-SHA256 signature (header x-pymaia-signature) on selected events. Returns the signing secret once — store it securely.

• Endpoint: POST /api/v1/create_webhook
• Scopes: notifications:write
• Módulo: requiere module_automatizaciones habilitado (si está apagado → 404).
• Parámetros: name, url, events (*obligatorio)

delete_alert_rule

Delete an alert rule.

• Endpoint: POST /api/v1/delete_alert_rule
• Scopes: notifications:write
• Parámetros: rule_id* (*obligatorio)

delete_webhook

Delete a webhook.

• Endpoint: POST /api/v1/delete_webhook
• Scopes: notifications:write
• Módulo: requiere module_automatizaciones habilitado (si está apagado → 404).
• Parámetros: webhook_id* (*obligatorio)

list_alert_rules

List alert rules for the org — thresholds on platform metrics that fire notifications when breached.

• Endpoint: POST /api/v1/list_alert_rules
• Scopes: notifications:read
• Parámetros: platform, enabled_only, limit

list_webhook_deliveries

List recent delivery attempts for a webhook (status, duration, response).

• Endpoint: POST /api/v1/list_webhook_deliveries
• Scopes: notifications:read
• Módulo: requiere module_automatizaciones habilitado (si está apagado → 404).
• Parámetros: webhook_id*, limit (*obligatorio)

list_webhooks

List outbound webhooks configured for the org (URL, subscribed events, last delivery status).

• Endpoint: POST /api/v1/list_webhooks
• Scopes: notifications:read
• Módulo: requiere module_automatizaciones habilitado (si está apagado → 404).
• Parámetros: ninguno

update_alert_rule

Update fields on an alert rule (enabled, threshold, channels, etc). Omit fields you do not want to change.

• Endpoint: POST /api/v1/update_alert_rule
• Scopes: notifications:write
• Parámetros: rule_id*, name, description, threshold, condition, comparison_period, enabled, channels (*obligatorio)

update_webhook

Update webhook (name/url/events/is_active).

• Endpoint: POST /api/v1/update_webhook
• Scopes: notifications:write
• Módulo: requiere module_automatizaciones habilitado (si está apagado → 404).
• Parámetros: webhook_id*, name, url, events, is_active (*obligatorio)

Brand IQ

get_brand_profile

Get the full brand profile for the active org: name, website, description, target customers, voice, value prop, colors, settings.

• Endpoint: POST /api/v1/get_brand_profile
• Scopes: brand:read
• Módulo: requiere module_brand_iq habilitado (si está apagado → 404).
• Parámetros: ninguno

run_brand_analyzer

Run the brand-analyzer edge function on the org website. Scrapes site, detects tech stack, infers voice/positioning, fills brand_* fields. Updates brand_analyzed_at.

• Endpoint: POST /api/v1/run_brand_analyzer
• Scopes: brand:write
• Módulo: requiere module_brand_iq habilitado (si está apagado → 404).
• Parámetros: ninguno

update_brand_profile

Update brand profile fields (description, target_customers, brand_voice, value_proposition, colors). Does not trigger re-analysis.

• Endpoint: POST /api/v1/update_brand_profile
• Scopes: brand:write
• Módulo: requiere module_brand_iq habilitado (si está apagado → 404).
• Parámetros: website_url, company_description, target_customers, brand_voice, value_proposition, brand_color_primary, brand_color_accent

CRM & Leads

create_contact

Create a CRM contact (person). Use tags[] to segment.

• Endpoint: POST /api/v1/create_contact
• Scopes: crm:write
• Módulo: requiere module_pymaia_crm habilitado (si está apagado → 404).
• Parámetros: full_name*, email, phone, company, source, tags (*obligatorio)

create_lead

Create a new lead. Optionally link to an existing contact by contact_id.

• Endpoint: POST /api/v1/create_lead
• Scopes: crm:write
• Módulo: requiere module_pymaia_crm habilitado (si está apagado → 404).
• Parámetros: title*, contact_id, status, value, currency, source (*obligatorio)

list_lead_activities

List activities (notes, calls, emails, stage changes) on a lead.

• Endpoint: POST /api/v1/list_lead_activities
• Scopes: crm:read
• Módulo: requiere module_pymaia_crm habilitado (si está apagado → 404).
• Parámetros: lead_id*, limit (*obligatorio)

list_leads

List CRM leads with status, value, assigned user, and linked contact.

• Endpoint: POST /api/v1/list_leads
• Scopes: crm:read
• Módulo: requiere module_pymaia_crm habilitado (si está apagado → 404).
• Parámetros: status, limit

query_contacts

Query CRM contacts with tags and source

• Endpoint: POST /api/v1/query_contacts
• Scopes: crm:read
• Parámetros: limit, search

update_lead

Update lead fields (status, value, assigned_to). Omit fields to keep unchanged.

• Endpoint: POST /api/v1/update_lead
• Scopes: crm:write
• Módulo: requiere module_pymaia_crm habilitado (si está apagado → 404).
• Parámetros: lead_id*, status, value, assigned_to, closed_at (*obligatorio)

Competitive

add_brand_competitor

Append a competitor to organizations.settings.competitors[] (BrandRef shape: id, name, website). Returns updated list.

• Endpoint: POST /api/v1/add_brand_competitor
• Scopes: brand:write
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: name*, website, notes (*obligatorio)

get_competitor

Full detail of a competitor profile including 4Ps JSON, SWOT, tech stack, messaging themes.

• Endpoint: POST /api/v1/get_competitor
• Scopes: competitive:read
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: competitor_id* (*obligatorio)

list_brand_competitors

List competitors from the BrandRef[] stored in organizations.settings.competitors (source of truth for Brand IQ CRUD).

• Endpoint: POST /api/v1/list_brand_competitors
• Scopes: brand:read
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: ninguno

list_competitor_ads

List ads from Meta Ad Library persisted for a competitor. Filter by active status and recency.

• Endpoint: POST /api/v1/list_competitor_ads
• Scopes: competitive:read
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: competitor_id, active_only, limit

list_competitor_snapshots

Time-series snapshots per competitor (weekly) — active ads count, messaging themes, pricing, site diffs.

• Endpoint: POST /api/v1/list_competitor_snapshots
• Scopes: competitive:read
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: competitor_id*, limit (*obligatorio)

list_competitors

List competitor profiles for the active org with enriched data (4Ps, SWOT, positioning, last analysis date).

• Endpoint: POST /api/v1/list_competitors
• Scopes: competitive:read
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: limit

regenerate_competitor_swot

Regenerate SWOT for a competitor using competitor-swot-generator. Uses latest snapshot + 4Ps data.

• Endpoint: POST /api/v1/regenerate_competitor_swot
• Scopes: competitive:write
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: competitor_id* (*obligatorio)

remove_brand_competitor

Remove a competitor by BrandRef id from organizations.settings.competitors[]. Does NOT delete competitor_profiles row — use delete_competitor_profile for that.

• Endpoint: POST /api/v1/remove_brand_competitor
• Scopes: brand:write
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: brand_ref_id* (*obligatorio)

run_competitive_gap_analysis

Cross-competitor gap analysis: opportunities, positioning holes, messaging gaps. Uses competitive-gap-analyzer.

• Endpoint: POST /api/v1/run_competitive_gap_analysis
• Scopes: competitive:write
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: ninguno

run_competitor_analyzer

Runs the competitor-analyzer edge function: scrapes the website, extracts 4Ps, value prop, tech stack, messaging. Updates competitor_profiles.

• Endpoint: POST /api/v1/run_competitor_analyzer
• Scopes: competitive:write
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: competitor_id* (*obligatorio)

suggest_competitors

Use competitor-suggester to propose new competitors based on the org brand profile + industry. Returns suggested names + domains; does NOT persist.

• Endpoint: POST /api/v1/suggest_competitors
• Scopes: competitive:read
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: count

sync_competitor_ads

Pull the latest Meta Ad Library snapshot for a competitor (competitor-ads-sync). Updates competitor_ads and marks stale ads inactive.

• Endpoint: POST /api/v1/sync_competitor_ads
• Scopes: competitive:write
• Módulo: requiere module_competitive habilitado (si está apagado → 404).
• Parámetros: competitor_id* (*obligatorio)

Ecommerce

list_abandoned_checkouts

List abandoned checkouts from Shopify/Tiendanube with recovery URLs.

• Endpoint: POST /api/v1/list_abandoned_checkouts
• Scopes: ecommerce:read
• Parámetros: days_back, recovered, limit

list_store_connections

List Shopify/Tiendanube store connections for the org (store_id, store_name, store_url, last_sync).

• Endpoint: POST /api/v1/list_store_connections
• Scopes: ecommerce:read
• Parámetros: platform

list_store_orders

List e-commerce store orders (Shopify/Tiendanube) for the org, filtered by date and/or status. Newest first.

• Endpoint: POST /api/v1/list_store_orders
• Scopes: ecommerce:read
• Parámetros: platform, date_from, date_to, status, limit

list_store_products

List store products (Shopify/Tiendanube). Filter by status and stock.

• Endpoint: POST /api/v1/list_store_products
• Scopes: ecommerce:read
• Parámetros: platform, status, in_stock_only, limit

optimize_product_content

Optimiza la ficha (título + descripción, on-brand + SEO) de uno o varios productos de la tienda (Shopify o Tiendanube) del cliente. Por defecto genera PREVIEW; apply=true escribe los cambios en Shopify (cobra créditos). Indicá los productos por nombre (se resuelven contra la tienda) o por id.

• Endpoint: POST /api/v1/optimize_product_content
• Scopes: ecommerce:write
• Parámetros: product_names, product_ids, apply

publish_to_store

Publica una landing o un artículo del blog del cliente como Página de su tienda ecommerce (Shopify o Tiendanube — detecta la conectada). Pasá type (“landing”|“blog”) y opcionalmente slug. Requiere permiso de contenido en la conexión de la tienda; si falta, avisa que hay que reconectar.

• Endpoint: POST /api/v1/publish_to_store
• Scopes: ecommerce:write
• Parámetros: type*, slug (*obligatorio)

query_carts

Query abandoned carts with recovery URLs

• Endpoint: POST /api/v1/query_carts
• Scopes: ecommerce:read
• Parámetros: limit

query_orders

Query e-commerce orders (Shopify/Tiendanube store orders). Returns orders with revenue, UTM attribution and customer journey when available.

• Endpoint: POST /api/v1/query_orders
• Scopes: ecommerce:read
• Parámetros: date_from, date_to, limit

query_products

Query product catalog with prices and stock (Omnisend product mirror).

• Endpoint: POST /api/v1/query_products
• Scopes: ecommerce:read
• Parámetros: limit, search

Email

send_daily_digest_email

Send the daily digest email for the org (calls daily-digest-email edge function). Uses the most recent daily report.

• Endpoint: POST /api/v1/send_daily_digest_email
• Scopes: reports:run
• Parámetros: ninguno

GEO

create_geo_query

Create a GEO tracked query to monitor brand visibility in AI engines (ChatGPT/Perplexity/Gemini).

• Endpoint: POST /api/v1/create_geo_query
• Scopes: brand:write
• Parámetros: query, brand_name, engines (*obligatorio)

list_geo_queries

List Generative Engine Optimization (GEO) tracked queries for the org — queries monitored in ChatGPT/Perplexity/Gemini to measure brand visibility in AI answers.

• Endpoint: POST /api/v1/list_geo_queries
• Scopes: analytics:read
• Parámetros: active_only, limit

list_geo_results

List GEO result samples per engine for a tracked query (brand_mentioned, position, snippet). Useful to see if the brand shows up in AI answers over time.

• Endpoint: POST /api/v1/list_geo_results
• Scopes: analytics:read
• Parámetros: geo_query_id*, engine, limit (*obligatorio)

General

disconnect_platform

Revoke a platform connection (sets status=revoked). Does NOT delete encrypted tokens — they are wiped by a separate cleanup job.

• Endpoint: POST /api/v1/disconnect_platform
• Scopes: connections:write
• Parámetros: connection_id* (*obligatorio)

generate_daily_report

Generate the daily morning report for the org (cross-channel KPIs, insights, recommended actions). Calls daily-report-generate edge function.

• Endpoint: POST /api/v1/generate_daily_report
• Scopes: reports:run
• Parámetros: date

get_data_catalog

Available metrics and dimensions for query_data (single source of truth).

• Endpoint: POST /api/v1/get_data_catalog
• Scopes: ecommerce:read
• Parámetros: ninguno

get_kpi_summary

Cross-platform KPI summary normalized to the org reporting currency (via exchange_rates). Returns per-platform spend/revenue/ROAS, store revenue, blended ad ROAS, store ROAS (revenue/spend), sessions and SEO clicks.

• Endpoint: POST /api/v1/get_kpi_summary
• Scopes: ads:read, analytics:read, ecommerce:read
• Parámetros: days_back

invite_user

Invite a user by email to join the active org with a role. Creates an invitations row with a 7-day token.

• Endpoint: POST /api/v1/invite_user
• Scopes: admin:*
• Parámetros: email*, role (*obligatorio)

propose_connect_platform

Guide the user to (re)connect a platform when its connection is missing or broken (expired token). Returns a deep-link to /settings/connections so the user can complete the OAuth flow. Use when a sync fails because there is no working connection.

• Endpoint: POST /api/v1/propose_connect_platform
• Scopes: connections:write
• Parámetros: platform* (*obligatorio)

query_data

FLEXIBLE store metrics query (semantic layer, single source of truth — matches dashboard/alerts). Compose {metric, dimensions[], filters, date range} to answer ANY store aggregation question without a dedicated tool. Sources: STORE, META ADS, GOOGLE ADS, ANALYTICS (GA4), SEO (Search Console), SOCIAL, EMAIL, CRM (contacts), MELI (MercadoLibre). Metrics/dimensions from different sources cannot be mixed (error lists valid ones). Call get_data_catalog for the full live list (grows without deploy).

• Endpoint: POST /api/v1/query_data
• Scopes: ecommerce:read
• Parámetros: metric*, dimensions, filters, date_from, date_to (*obligatorio)

query_ga4_funnel

Query GA4 ecommerce funnel events (view_item, add_to_cart, begin_checkout, purchase) by date range. Use for drop-off analysis.

• Endpoint: POST /api/v1/query_ga4_funnel
• Scopes: analytics:read
• Parámetros: date_from, date_to, property_id, limit

run_readonly_sql

ESCAPE HATCH (advanced): run ONE read-only SELECT against this org’s data, RLS-isolated (cannot see other orgs, cannot write). Use ONLY when query_data does not cover the question. Tables: store_orders (+ store_connections via store_connection_id; store_orders has no org_id), meta_ad_creatives, ad_accounts. Return explicit columns. Prefer query_data when it fits.

• Endpoint: POST /api/v1/run_readonly_sql
• Scopes: ecommerce:read
• Parámetros: sql* (*obligatorio)

update_org_channels

Update the org notification channels (Slack webhook, WhatsApp phone, quiet hours). Pass only the fields you want to change. Pass an empty string "" to clear a field.

• Endpoint: POST /api/v1/update_org_channels
• Scopes: notifications:write
• Parámetros: slack_webhook_url, whatsapp_phone, notification_quiet_hours_start, notification_quiet_hours_end

Growth Plan

delete_account_plan_objective

Delete an account plan objective. Scoped to the current org.

• Endpoint: POST /api/v1/delete_account_plan_objective
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

delete_content_plan_ad

Delete a content plan ad. Scoped to the current org.

• Endpoint: POST /api/v1/delete_content_plan_ad
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

delete_growth_plan_dont

Delete a growth plan don’t. Scoped to the current org.

• Endpoint: POST /api/v1/delete_growth_plan_dont
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

delete_growth_plan_phase

Delete a growth plan phase. Scoped to the current org.

• Endpoint: POST /api/v1/delete_growth_plan_phase
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

delete_media_plan_item

Delete a media plan item. Scoped to the current org.

• Endpoint: POST /api/v1/delete_media_plan_item
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

query_account_plan

List account plan objectives (strategic goals by front with baseline/target/current values and health status) for the org, ordered by sort_order. Use to get objective ids before upsert/delete.

• Endpoint: POST /api/v1/query_account_plan
• Scopes: workspace:read
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: limit

query_content_plan

List content plan ads (creative concepts mapped to funnel stage / awareness level with copy and briefs) for the org, ordered by sort_order. Use to get ad ids before upsert/delete.

• Endpoint: POST /api/v1/query_content_plan
• Scopes: workspace:read
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: limit

query_growth_plan

List the growth plan for the org: phases (budget split by funnel stage with ICP, platforms, creative/copy angle, CTA, KPIs) and don’ts (rules to avoid). Both ordered by sort_order. Use to get phase/dont ids before upsert/delete.

• Endpoint: POST /api/v1/query_growth_plan
• Scopes: workspace:read
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: limit

query_media_plan

List media plan items (planned campaigns by platform/funnel stage with budgets and KPIs) for the org, ordered by sort_order. Use to get item ids before upsert/delete.

• Endpoint: POST /api/v1/query_media_plan
• Scopes: workspace:read
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: limit

upsert_account_plan_objective

Create or update an account plan objective. If id is provided, updates that row (by id+org); otherwise inserts a new one. Only the fields you pass are written. Scoped to the current org.

• Endpoint: POST /api/v1/upsert_account_plan_objective
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id, front, title, metric_key, unit, currency_code, direction, baseline_value, target_value, current_value, timeframe, period_start, period_end, owner_label, priority, lifecycle_status, rationale, sort_order

upsert_content_plan_ad

Create or update a content plan ad. If id is provided, updates that row (by id+org); otherwise inserts a new one. Only the fields you pass are written. Scoped to the current org.

• Endpoint: POST /api/v1/upsert_content_plan_ad
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id, framework_ad_id, funnel_stage, awareness_level, format, status, campaign_destination, copy, creative_brief, production_notes, owner, ad_link, start_date, live_date, notes, phase, sort_order

upsert_growth_plan_dont

Create or update a growth plan don’t (a rule to avoid). If id is provided, updates that row (by id+org); otherwise inserts a new one. Only the fields you pass are written. Scoped to the current org.

• Endpoint: POST /api/v1/upsert_growth_plan_dont
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id, rule, rationale, horizon_months, active, sort_order

upsert_growth_plan_phase

Create or update a growth plan phase. If id is provided, updates that row (by id+org); otherwise inserts a new one. Only the fields you pass are written. Scoped to the current org.

• Endpoint: POST /api/v1/upsert_growth_plan_phase
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id, phase, budget_pct, icp_label, platforms, creative_dominant, copy_angle, cta, kpis, period_months, is_active, sort_order

upsert_media_plan_item

Create or update a media plan item. If id is provided, updates that row (by id+org); otherwise inserts a new one. Only the fields you pass are written. Scoped to the current org.

• Endpoint: POST /api/v1/upsert_media_plan_item
• Scopes: workspace:write
• Módulo: requiere module_growth_plan habilitado (si está apagado → 404).
• Parámetros: id, platform, funnel_stage, campaign_name, objective, budget_pct, budget_amount, bidding_strategy, kpi_primary, kpi_target, creative_format, notes, is_active, sort_order

MercadoLibre

list_meli_listings

List MercadoLibre listings with price, stock, visits.

• Endpoint: POST /api/v1/list_meli_listings
• Scopes: ecommerce:read
• Módulo: requiere module_mercadolibre habilitado (si está apagado → 404).
• Parámetros: status, search, limit

list_meli_orders

List MercadoLibre orders by date range.

• Endpoint: POST /api/v1/list_meli_orders
• Scopes: ecommerce:read
• Módulo: requiere module_mercadolibre habilitado (si está apagado → 404).
• Parámetros: date_from, date_to, status, limit

list_meli_questions

List MercadoLibre pre-purchase questions. Default: unanswered only.

• Endpoint: POST /api/v1/list_meli_questions
• Scopes: ecommerce:read
• Módulo: requiere module_mercadolibre habilitado (si está apagado → 404).
• Parámetros: status, limit

optimize_meli_listing

Optimiza el título (máx 60, keyword-first, sin texto promocional que ML modera) y la descripción de una o varias publicaciones de MercadoLibre del cliente con IA. Por defecto PREVIEW; apply=true escribe en MercadoLibre (cobra créditos). Indicá por nombre (listing_names) o por id (listing_ids).

• Endpoint: POST /api/v1/optimize_meli_listing
• Scopes: ecommerce:write
• Módulo: requiere module_mercadolibre habilitado (si está apagado → 404).
• Parámetros: listing_names, listing_ids, apply

propose_answer_meli_question

Propose an answer to a MercadoLibre question. Creates a pending agent_action that must be approved via approve_action.

• Endpoint: POST /api/v1/propose_answer_meli_question
• Scopes: ecommerce:write
• Módulo: requiere module_mercadolibre habilitado (si está apagado → 404).
• Parámetros: question_id, answer_text (*obligatorio)

Org & Connections

get_organization_info

Get organization details and settings

• Endpoint: POST /api/v1/get_organization_info
• Scopes: agents:read
• Parámetros: ninguno

list_connections

List all platform connections for the organization with sync status, account health and a needs_reconnection flag. Use needs_reconnection/stale_hours to tell “empty because disconnected/expired” apart from “empty because genuinely zero”.

• Endpoint: POST /api/v1/list_connections
• Scopes: connections:read
• Parámetros: ninguno

list_connections_detail

Full details of all platform_connections for the org (status, last_sync, errors). Companion to list_connections which only gives summaries.

• Endpoint: POST /api/v1/list_connections_detail
• Scopes: connections:read
• Parámetros: ninguno

list_invitations

List pending and accepted invitations for the active org.

• Endpoint: POST /api/v1/list_invitations
• Scopes: admin:*
• Parámetros: include_accepted, limit

list_members

List users of the active org with their role. Includes profile info (name, avatar).

• Endpoint: POST /api/v1/list_members
• Scopes: admin:*
• Parámetros: ninguno

remove_member

Remove a user from the active org.

• Endpoint: POST /api/v1/remove_member
• Scopes: admin:*
• Parámetros: user_id* (*obligatorio)

revoke_invitation

Revoke a pending invitation (hard delete).

• Endpoint: POST /api/v1/revoke_invitation
• Scopes: admin:*
• Parámetros: invitation_id* (*obligatorio)

trigger_sync

Trigger a data sync for a specific platform connection

• Endpoint: POST /api/v1/trigger_sync
• Scopes: connections:write
• Parámetros: platform* (*obligatorio)

update_member_role

Change a user role in the active org. Roles: admin, member, viewer.

• Endpoint: POST /api/v1/update_member_role
• Scopes: admin:*
• Parámetros: user_id, role (*obligatorio)

Organic Social

list_social_accounts

List organic social accounts (Instagram, TikTok, Facebook, LinkedIn) with followers count.

• Endpoint: POST /api/v1/list_social_accounts
• Scopes: analytics:read
• Módulo: requiere module_organic_social habilitado (si está apagado → 404).
• Parámetros: ninguno

list_social_metrics

Time-series daily metrics per social account (followers, reach, impressions, engagement_rate).

• Endpoint: POST /api/v1/list_social_metrics
• Scopes: analytics:read
• Módulo: requiere module_organic_social habilitado (si está apagado → 404).
• Parámetros: social_account_id*, days_back (*obligatorio)

list_social_posts

List organic social posts with engagement metrics (likes, comments, reach, engagement_rate).

• Endpoint: POST /api/v1/list_social_posts
• Scopes: analytics:read
• Módulo: requiere module_organic_social habilitado (si está apagado → 404).
• Parámetros: social_account_id, days_back, limit

Recommendations

apply_recommendation

Mark a recommendation as applied (done). Use after the suggested change was actually carried out. Internal state only — does NOT mutate any external platform.

• Endpoint: POST /api/v1/apply_recommendation
• Scopes: notifications:write
• Parámetros: recommendation_id* (*obligatorio)

approve_action

Approve a pending agent action and execute it. Marks the action as approved, then calls the execute-action edge function to actually run the mutation.

• Endpoint: POST /api/v1/approve_action
• Scopes: actions:approve
• Parámetros: action_id* (*obligatorio)

dismiss_recommendation

Dismiss a recommendation permanently (it will not reappear). Use when the suggestion is not relevant or the user rejected it.

• Endpoint: POST /api/v1/dismiss_recommendation
• Scopes: notifications:write
• Parámetros: recommendation_id*, reason (*obligatorio)

list_action_history

List historical agent actions (executed, rejected, failed, expired, or approved but not yet executed). Useful for audit trails.

• Endpoint: POST /api/v1/list_action_history
• Scopes: actions:read
• Parámetros: status, agent_slug, limit

list_credit_transactions

List credit transactions (grants, AI consumption, purchases, admin adjustments) for the org.

• Endpoint: POST /api/v1/list_credit_transactions
• Scopes: billing:read
• Parámetros: type, limit

list_guardrails

List guardrail rules that gate agent actions (what requires approval, auto-approval thresholds, cooldowns, max auto amounts).

• Endpoint: POST /api/v1/list_guardrails
• Scopes: actions:read
• Parámetros: agent_slug, action_type

list_notifications

List recent notifications for the organization

• Endpoint: POST /api/v1/list_notifications
• Scopes: notifications:read
• Parámetros: module, unread_only, limit

list_pending_actions

List agent actions awaiting human approval. These were proposed by agents but blocked by guardrails (e.g., destructive ops like pausing campaigns, changing budgets, updating prices).

• Endpoint: POST /api/v1/list_pending_actions
• Scopes: actions:read
• Parámetros: agent_slug, action_type, limit

list_recommendations

List recommendations from the Recommendations Hub for the org. Use to get recommendation IDs before applying/snoozing/dismissing. Filter by status (default “new”) and severity.

• Endpoint: POST /api/v1/list_recommendations
• Scopes: notifications:read
• Parámetros: status, severity, module, limit

mark_notification_read

Mark a notification as read. Pass all=true to mark every unread notification for the org.

• Endpoint: POST /api/v1/mark_notification_read
• Scopes: notifications:write
• Parámetros: notification_id, all

reject_action

Reject a pending agent action. The action will not be executed.

• Endpoint: POST /api/v1/reject_action
• Scopes: actions:approve
• Parámetros: action_id*, reason (*obligatorio)

snooze_recommendation

Snooze a recommendation for a number of hours (it reappears after). Use when the suggestion is valid but not actionable right now.

• Endpoint: POST /api/v1/snooze_recommendation
• Scopes: notifications:write
• Parámetros: recommendation_id*, hours (*obligatorio)

Sites

create_site

Crea el sitio web hosteado del cliente (subdominio en pymaia.app + página “Próximamente”). Primer paso antes de generar landings/blog. Pasá “name” (negocio) y opcionalmente “slug”. Requiere que el plan incluya sitio web.

• Endpoint: POST /api/v1/create_site
• Scopes: workspace:write
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: name, slug

delete_blog_post

Borra un artículo del blog del cliente por slug o título. Si estaba publicado, se quita al volver a publicar.

• Endpoint: POST /api/v1/delete_blog_post
• Scopes: workspace:write
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: slug* (*obligatorio)

delete_landing

Borra una landing (página) del sitio del cliente por slug o título. NO borra el home. Si estaba publicada, se quita al volver a publicar.

• Endpoint: POST /api/v1/delete_landing
• Scopes: workspace:write
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: slug* (*obligatorio)

generate_landing

Genera con IA el contenido de una landing del sitio hosteado del cliente, grounded en la marca. Si pasás “title” crea una página nueva; si no, reescribe el home. Pasá “brief” (negocio/objetivo) o “url” (web existente a reescribir). Queda en borrador. Requiere que la org tenga un sitio creado.

• Endpoint: POST /api/v1/generate_landing
• Scopes: workspace:write
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: brief, url, title

list_blog_posts

Lista los artículos del blog hosteado del cliente (título, slug, estado). Scoped a la org actual.

• Endpoint: POST /api/v1/list_blog_posts
• Scopes: workspace:read
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: limit

list_landings

Lista las landings (páginas) del sitio hosteado del cliente, con su path, título y estado (borrador/publicada). Scoped a la org actual.

• Endpoint: POST /api/v1/list_landings
• Scopes: workspace:read
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: ninguno

publish_site

Publica el sitio hosteado del cliente: pone EN VIVO las landings actuales en el subdominio (y dominio propio si hay). El contenido queda visible al público — confirmá antes.

• Endpoint: POST /api/v1/publish_site
• Scopes: workspace:write
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: ninguno

write_blog_post

Escribe con IA un artículo de blog SEO para el sitio hosteado del cliente, a partir de un tema, grounded en la marca. Queda en borrador. Requiere que la org tenga un sitio creado.

• Endpoint: POST /api/v1/write_blog_post
• Scopes: workspace:write
• Módulo: requiere module_sites habilitado (si está apagado → 404).
• Parámetros: topic* (*obligatorio)

Spaces

connect_space_nodes

Connect two nodes in a space with an edge (source output → target input). Use to build the flow (e.g. brief → ai-text-gen → ai-image-gen). Both nodes must exist in the same space.

• Endpoint: POST /api/v1/connect_space_nodes
• Scopes: workspace:write
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: space_id, source_node_id, target_node_id*, source_handle, target_handle, label (*obligatorio)

create_space

Create a new creative space (empty canvas).

• Endpoint: POST /api/v1/create_space
• Scopes: workspace:write
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: name*, description, tags (*obligatorio)

create_space_node

Create a node in a space (canvas). For AI generator nodes (ai-image-gen, ai-text-gen, ai-video-gen, ai-static-gen) you can preload the prompt/params in config; the node stays in draft and generation is triggered later. Returns the created node id (use it in connect_space_nodes).

• Endpoint: POST /api/v1/create_space_node
• Scopes: workspace:write
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: space_id, type, title, content, position_x, position_y, config, platform, source (*obligatorio)

create_workspace_file

Create a workspace file (markdown content). Category: brand, research, strategy, report, other.

• Endpoint: POST /api/v1/create_workspace_file
• Scopes: workspace:write
• Parámetros: name, category, content*, is_pinned (*obligatorio)

delete_space_edge

Delete an edge (connection) between nodes in a space by id. space_edges has no org_id: the edge’s space is verified to belong to the org before deleting.

• Endpoint: POST /api/v1/delete_space_edge
• Scopes: workspace:write
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

delete_space_node

Delete a node in a space by id.

• Endpoint: POST /api/v1/delete_space_node
• Scopes: workspace:write
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: id* (*obligatorio)

delete_workspace_file

Delete a workspace file.

• Endpoint: POST /api/v1/delete_workspace_file
• Scopes: workspace:write
• Parámetros: file_id* (*obligatorio)

get_space

Get a space with its nodes and edges (canvas graph).

• Endpoint: POST /api/v1/get_space
• Scopes: workspace:read
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: space_id* (*obligatorio)

get_workspace_file

Read the full markdown content of a workspace file by id.

• Endpoint: POST /api/v1/get_workspace_file
• Scopes: workspace:read
• Parámetros: file_id* (*obligatorio)

list_spaces

List creative spaces (canvases with nodes/workflows) for the org.

• Endpoint: POST /api/v1/list_spaces
• Scopes: workspace:read
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: status, limit

list_workspace_files

List workspace files (markdown artifacts like business-profile.md, brand-guidelines.md, strategy docs, reports) for the org.

• Endpoint: POST /api/v1/list_workspace_files
• Scopes: workspace:read
• Parámetros: category, pinned_only, limit

update_space_node

Update a node in a space by id. Only the fields you pass are written (title, content, status, position, config).

• Endpoint: POST /api/v1/update_space_node
• Scopes: workspace:write
• Módulo: requiere module_spaces habilitado (si está apagado → 404).
• Parámetros: id*, title, content, status, position_x, position_y, config (*obligatorio)

update_workspace_file

Update a workspace file (name, category, content, is_pinned).

• Endpoint: POST /api/v1/update_workspace_file
• Scopes: workspace:write
• Parámetros: file_id*, name, category, content, is_pinned (*obligatorio)

Tasks

activate_template

Create a task from a template

• Endpoint: POST /api/v1/activate_template
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: template_id*, name_override (*obligatorio)

complete_task

Mark a manual action task as completed. Requires the lease_token from lease_task. The system will trigger the relevant platform sync; verification of the change happens automatically based on the task verifier_kind.

• Endpoint: POST /api/v1/complete_task
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id, lease_token, summary*, screenshots (*obligatorio)

create_task

Create a new AI task. The task will be executed by the specified agent (or auto-routed if no agent specified).

• Endpoint: POST /api/v1/create_task
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: name, objective, agent_slug, task_type, cron_expr, priority, success_criteria, max_cost_usd (*obligatorio)

get_task_details

Get full details of a manual_action_task: steps array, expected_outcome, target_url, verifier config. Use this BEFORE lease_task to understand what needs to be done.

• Endpoint: POST /api/v1/get_task_details
• Scopes: tasks:read
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id* (*obligatorio)

lease_task

Acquire an exclusive lease on a manual action task before starting work. Returns the steps + target_url + a lease_token. The lease expires in 15 minutes; call complete_task or report_task_blocked before then. Without a lease, complete_task will reject your call.

• Endpoint: POST /api/v1/lease_task
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id* (*obligatorio)

list_pending_browser_tasks

List manual_action_tasks pending or in-progress for this org. Returns tasks the user (or Claude in the browser) should execute manually because the underlying platform has no API. Each task has step-by-step instructions, a target URL, and a verifier_kind.

• Endpoint: POST /api/v1/list_pending_browser_tasks
• Scopes: tasks:read
• Parámetros: limit, platform

list_suggestions

List AI-generated task suggestions for the organization

• Endpoint: POST /api/v1/list_suggestions
• Scopes: tasks:read
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: ninguno

list_task_runs

Get execution history for a task

• Endpoint: POST /api/v1/list_task_runs
• Scopes: tasks:read
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id*, limit (*obligatorio)

list_tasks

List all AI tasks (scheduled, recurring, event-triggered) for the organization

• Endpoint: POST /api/v1/list_tasks
• Scopes: tasks:read
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: status, task_type

list_templates

List available task templates that can be activated

• Endpoint: POST /api/v1/list_templates
• Scopes: tasks:read
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: category

report_task_blocked

Report that a manual action task could not be completed. Use this when the steps fail (e.g. UI changed, missing permission, error). The lease is released and the task can be retried.

• Endpoint: POST /api/v1/report_task_blocked
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id, lease_token, reason*, current_step_n (*obligatorio)

run_task

Execute a task immediately. Returns the result of the agent execution.

• Endpoint: POST /api/v1/run_task
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id* (*obligatorio)

update_task

Update a task (pause, resume, change priority, etc.)

• Endpoint: POST /api/v1/update_task
• Scopes: tasks:write
• Módulo: requiere module_tasks habilitado (si está apagado → 404).
• Parámetros: task_id*, status, priority, objective, cron_expr (*obligatorio)

WhatsApp

list_whatsapp_conversations

List WhatsApp conversations for the org with last message preview.

• Endpoint: POST /api/v1/list_whatsapp_conversations
• Scopes: crm:read
• Módulo: requiere module_vendedor habilitado (si está apagado → 404).
• Parámetros: status, limit

list_whatsapp_messages

List messages of a WhatsApp conversation. Org is enforced via the conversation FK.

• Endpoint: POST /api/v1/list_whatsapp_messages
• Scopes: crm:read
• Módulo: requiere module_vendedor habilitado (si está apagado → 404).
• Parámetros: conversation_id*, limit (*obligatorio)