associate_whatsapp_direct_numbers
ChatGPTQueue one or more allowed customer phone numbers for Cortex WhatsApp direct routing. The gateway forwards the request to mk1-tasks, which normalizes the numbers, checks whether any number already belongs to another influencer, and enqueues the association task when there are no conflicts. Returns { status: "queued", taskId } on success or { error: "phone_number_conflict", requested_influencer_id, conflicts: [...] } when a number is already mapped elsewhere.
associate_whatsapp_direct_numbers
ChatGPTQueue one or more allowed customer phone numbers for Cortex WhatsApp direct routing. The gateway forwards the request to mk1-tasks, which normalizes the numbers, checks whether any number already belongs to another influencer, and enqueues the association task when there are no conflicts. Returns { status: "queued", taskId } on success or { error: "phone_number_conflict", requested_influencer_id, conflicts: [...] } when a number is already mapped elsewhere.
bootstrap_discord_channel
ChatGPTQueue mk1-tasks bootstrap for the influencer's Discord operator channel. This creates or repairs the stored Discord mapping asynchronously through mk1-tasks. The downstream bootstrap creates the role, private channel, and permanent invite when needed. Returns { status: "queued", taskId } on success.
bootstrap_discord_channel
ChatGPTQueue mk1-tasks bootstrap for the influencer's Discord operator channel. This creates or repairs the stored Discord mapping asynchronously through mk1-tasks. The downstream bootstrap creates the role, private channel, and permanent invite when needed. Returns { status: "queued", taskId } on success.
create_agent
ChatGPTCreate a new Ninjo agent with its initial system prompt. Creates the Agent, AgentConfig, and first AgentPromptVersion atomically, with safe humanization defaults (message chunking on, MEDIUM delay split, 2–6s response delay — all overridable). Returns { agent_id, agent_config_id, prompt_version_id, completeness }. completeness is the deterministic build/wiring audit of the new agent: a fresh agent reports critical gaps by design (no terminal stop, not linked to a connected account) — wire them with scaffold_agent_activation before treating it as done.
create_agent
ChatGPTCreate a new Ninjo agent with its initial system prompt. Creates the Agent, AgentConfig, and first AgentPromptVersion atomically, with safe humanization defaults (message chunking on, MEDIUM delay split, 2–6s response delay — all overridable). Returns { agent_id, agent_config_id, prompt_version_id, completeness }. completeness is the deterministic build/wiring audit of the new agent: a fresh agent reports critical gaps by design (no terminal stop, not linked to a connected account) — wire them with scaffold_agent_activation before treating it as done.
create_document
ChatGPTUpload a context document for a Ninjo agent. If file_base64 is provided, uploads to S3 at agents/{influencer_id}/context/{uuid}/{file_name}. Returns the created document row.
create_document
ChatGPTUpload a context document for a Ninjo agent. If file_base64 is provided, uploads to S3 at agents/{influencer_id}/context/{uuid}/{file_name}. Returns the created document row.
create_feedback_upload_url
ChatGPTStep 1 of reporting feedback (optional, only when you want to attach the agent session). Returns a short-lived presigned S3 PUT URL + s3_key. Write the full agent session to a file and PUT it to upload_url (no special headers needed) — the bytes never pass through the tool-call payload or model context. Then call report_feedback with the returned s3_key as session_s3_key. Returns { upload_url, s3_key }.
create_feedback_upload_url
ChatGPTStep 1 of reporting feedback (optional, only when you want to attach the agent session). Returns a short-lived presigned S3 PUT URL + s3_key. Write the full agent session to a file and PUT it to upload_url (no special headers needed) — the bytes never pass through the tool-call payload or model context. Then call report_feedback with the returned s3_key as session_s3_key. Returns { upload_url, s3_key }.
create_resource_upload_url
ChatGPTStep 1 of uploading an agent-sendable audio/image clip. Returns a presigned S3 PUT URL + s3_key — the file bytes are NOT sent through this tool. AUDIO must be M4A/AAC (MP3 rejected); IMAGE must be JPG/PNG/GIF. Next: PUT the file to upload_url with the same Content-Type header (e.g. curl -T file.m4a -H 'Content-Type: audio/mp4' '<upload_url>'), then call register_creator_resource with the s3_key. Returns { upload_url, s3_key }.
create_resource_upload_url
ChatGPTStep 1 of uploading an agent-sendable audio/image clip. Returns a presigned S3 PUT URL + s3_key — the file bytes are NOT sent through this tool. AUDIO must be M4A/AAC (MP3 rejected); IMAGE must be JPG/PNG/GIF. Next: PUT the file to upload_url with the same Content-Type header (e.g. curl -T file.m4a -H 'Content-Type: audio/mp4' '<upload_url>'), then call register_creator_resource with the s3_key. Returns { upload_url, s3_key }.
create_thread
ChatGPTCreate a new Cortex thread (conversation between the influencer and their AI agent). Returns the new conversation object with id, title, status, created_at. Uses JWT for RLS when available; with API key/admin, pass influencer_id.
create_thread
ChatGPTCreate a new Cortex thread (conversation between the influencer and their AI agent). Returns the new conversation object with id, title, status, created_at. Uses JWT for RLS when available; with API key/admin, pass influencer_id.
create_trigger
ChatGPTCreate a trigger for a Ninjo agent. type selects the variant and which fields apply: • keywords — DM keyword trigger: keyword (required), match_mode (KEYWORD_ONLY|ANYWHERE), allow_typo. • all-messages — fires on every DM or comment: keyword must be ALL_DM or ALL_COMMENTS; prompt_evaluator optional. • comments — comment keyword trigger: keyword (required), match_mode, allow_typo, responses (public reply templates). • ads — ad referral trigger: ad_id (required). • outgoing-messages — fires on an outgoing message keyword: keyword (required), assign_unpaused. • instagram-story — story reply trigger: story_id (required), story_created_at. Returns the created trigger row.
create_trigger
ChatGPTCreate a trigger for a Ninjo agent. type selects the variant and which fields apply: • keywords — DM keyword trigger: keyword (required), match_mode (KEYWORD_ONLY|ANYWHERE), allow_typo. • all-messages — fires on every DM or comment: keyword must be ALL_DM or ALL_COMMENTS; prompt_evaluator optional. • comments — comment keyword trigger: keyword (required), match_mode, allow_typo, responses (public reply templates). • ads — ad referral trigger: ad_id (required). • outgoing-messages — fires on an outgoing message keyword: keyword (required), assign_unpaused. • instagram-story — story reply trigger: story_id (required), story_created_at. Returns the created trigger row.
delete_agent
ChatGPTPermanently delete a Ninjo agent and all its associated data (triggers, prompt versions, documents, workflow relations, config). Cannot delete agents with active conversations — will return an error with the count. Returns { success: true }.
delete_agent
ChatGPTPermanently delete a Ninjo agent and all its associated data (triggers, prompt versions, documents, workflow relations, config). Cannot delete agents with active conversations — will return an error with the count. Returns { success: true }.
delete_contact_limit
ChatGPTDelete a contact limit by id. Returns { success: true }.
delete_contact_limit
ChatGPTDelete a contact limit by id. Returns { success: true }.
delete_creator_resource
ChatGPTDelete a creator resource (removes the S3 object and the DB row). Returns { deleted, resource_id }.
delete_creator_resource
ChatGPTDelete a creator resource (removes the S3 object and the DB row). Returns { deleted, resource_id }.
delete_custom_notification
ChatGPTDelete a custom notification by id. Returns { success: true }.
delete_custom_notification
ChatGPTDelete a custom notification by id. Returns { success: true }.
delete_custom_property
ChatGPTDelete a custom property by id. Returns { success: true }.
delete_custom_property
ChatGPTDelete a custom property by id. Returns { success: true }.
delete_document
ChatGPTDelete a context document from a Ninjo agent. If the document has an S3 file_key, deletes it from S3 as well. Returns { success: true }.
delete_document
ChatGPTDelete a context document from a Ninjo agent. If the document has an S3 file_key, deletes it from S3 as well. Returns { success: true }.
delete_notification_destination
ChatGPTDelete a notification destination by id. Returns { success: true }.
delete_notification_destination
ChatGPTDelete a notification destination by id. Returns { success: true }.
delete_thread
ChatGPTDelete a Cortex thread and all its messages.
delete_thread
ChatGPTDelete a Cortex thread and all its messages.
delete_trigger
ChatGPTDelete a trigger by ID and type. type must be one of: keywords, all-messages, comments, ads, outgoing-messages, instagram-story. Cascades to trigger_negative_config if present. Returns { success: true }.
delete_trigger
ChatGPTDelete a trigger by ID and type. type must be one of: keywords, all-messages, comments, ads, outgoing-messages, instagram-story. Cascades to trigger_negative_config if present. Returns { success: true }.
delete_trigger_negative_config
ChatGPTRemove the negative config from a trigger. The trigger itself is not affected.
delete_trigger_negative_config
ChatGPTRemove the negative config from a trigger. The trigger itself is not affected.
delete_whatsapp_template_definition
ChatGPTDelete a WhatsApp template definition by id (via mk1-chat). Refused with 409 if any notification destination still references it (detach or delete those first) — the definition is never silently orphaned. Returns { ok, influencerId, id }.
delete_whatsapp_template_definition
ChatGPTDelete a WhatsApp template definition by id (via mk1-chat). Refused with 409 if any notification destination still references it (detach or delete those first) — the definition is never silently orphaned. Returns { ok, influencerId, id }.
delete_workflow
ChatGPTDelete a workflow by id. Returns { success: true }.
delete_workflow
ChatGPTDelete a workflow by id. Returns { success: true }.
deploy_agent_sdk
ChatGPTDeploy the Cortex SDK (system.md + the 8 v5Config fields) to a Ninjo agent in one correct-by-construction call. Bakes the multi-step deploy the cortex skills enforce but the raw tools don't: (1) update the prompt column if system changed, (2) merge changed v5Config fields, (3) re-sync trigger_keywords whenever keywords is provided — so keyword changes are always dual-written (v5Config context AND what actually fires) and system never lands in v5Config. Diffs each provided field against the live config and only calls what changed; omitted fields are left untouched (PATCH semantics — there is no set-to-null). Then re-fetches and verifies (version bumped, fields match, no v5Config↔trigger_keywords drift). On verified=false or partial=true the deploy did NOT fully succeed: pass rollback_version_id to restore_prompt_version to revert both prompt and config. Returns the deploy report. IMPORTANT: this ships the agent's MESSAGES only (prompt + v5Config). It does NOT create the contact limits, custom notifications, or follow-up workflows that turn a prompt into a working agent — build those separately (upsert_contact_limit / upsert_custom_notification / upsert_workflow), gated on your custom properties. verified=true means the messages are live, not that the system is complete. The result also carries a completeness report (the same deterministic build/wiring audit as diagnose_agent mode=quick) run AFTER the deploy — resolve its critical/warn findings (or run scaffold_agent_activation) before treating the agent as done.
deploy_agent_sdk
ChatGPTDeploy the Cortex SDK (system.md + the 8 v5Config fields) to a Ninjo agent in one correct-by-construction call. Bakes the multi-step deploy the cortex skills enforce but the raw tools don't: (1) update the prompt column if system changed, (2) merge changed v5Config fields, (3) re-sync trigger_keywords whenever keywords is provided — so keyword changes are always dual-written (v5Config context AND what actually fires) and system never lands in v5Config. Diffs each provided field against the live config and only calls what changed; omitted fields are left untouched (PATCH semantics — there is no set-to-null). Then re-fetches and verifies (version bumped, fields match, no v5Config↔trigger_keywords drift). On verified=false or partial=true the deploy did NOT fully succeed: pass rollback_version_id to restore_prompt_version to revert both prompt and config. Returns the deploy report. IMPORTANT: this ships the agent's MESSAGES only (prompt + v5Config). It does NOT create the contact limits, custom notifications, or follow-up workflows that turn a prompt into a working agent — build those separately (upsert_contact_limit / upsert_custom_notification / upsert_workflow), gated on your custom properties. verified=true means the messages are live, not that the system is complete. The result also carries a completeness report (the same deterministic build/wiring audit as diagnose_agent mode=quick) run AFTER the deploy — resolve its critical/warn findings (or run scaffold_agent_activation) before treating the agent as done.
diagnose_agent
ChatGPTAudit a live agent and return ranked defects, each with the exact fix tool. An agent is a SYSTEM, not a prompt: this is the "definition of done" as code. mode="quick" (default) — DETERMINISTIC tier only. Free, fast, reproducible: run it after every iterate. Service-role checks: no terminal contact limit, an active agent not linked to a connected account, ungated follow-ups, string-typed gating properties, hand-made properties duplicating an auto one (e.g. agendo_llamada ↔ call_booked), inert properties, missing conversion notification, robotic cadence (humanization off), and v5Config↔trigger_keywords drift. score/complete come from this tier. mode="full" — also runs two LLM-graded tiers (costs model calls — run pre-deploy or periodically, NOT every iteration): - behavioral: samples recent low-quality conversations (bad/stuck/low-happy) and grades them server-side — filter leak, NO_RESPONSE paraphrase, reasoning leak, premature booking. Needs a JWT-scoped token. Returns the sampled transcripts too. - prompt_audit: grades the deployed SDK (system.md + v5Config) against the Best-Practices rubric BP-2…BP-10 (fetched live from the wiki) — contradictions, example coverage, unguarded actions, voice drift, stale CTAs. Returns { agent_id, checked_at, mode, score (0–100, deterministic), complete, findings, behavioral, prompt_audit }. Resolve every critical/warn finding (across all tiers) before treating the agent as done.
diagnose_agent
ChatGPTAudit a live agent and return ranked defects, each with the exact fix tool. An agent is a SYSTEM, not a prompt: this is the "definition of done" as code. mode="quick" (default) — DETERMINISTIC tier only. Free, fast, reproducible: run it after every iterate. Service-role checks: no terminal contact limit, an active agent not linked to a connected account, ungated follow-ups, string-typed gating properties, hand-made properties duplicating an auto one (e.g. agendo_llamada ↔ call_booked), inert properties, missing conversion notification, robotic cadence (humanization off), and v5Config↔trigger_keywords drift. score/complete come from this tier. mode="full" — also runs two LLM-graded tiers (costs model calls — run pre-deploy or periodically, NOT every iteration): - behavioral: samples recent low-quality conversations (bad/stuck/low-happy) and grades them server-side — filter leak, NO_RESPONSE paraphrase, reasoning leak, premature booking. Needs a JWT-scoped token. Returns the sampled transcripts too. - prompt_audit: grades the deployed SDK (system.md + v5Config) against the Best-Practices rubric BP-2…BP-10 (fetched live from the wiki) — contradictions, example coverage, unguarded actions, voice drift, stale CTAs. Returns { agent_id, checked_at, mode, score (0–100, deterministic), complete, findings, behavioral, prompt_audit }. Resolve every critical/warn finding (across all tiers) before treating the agent as done.
generate_image
ChatGPTGenerate an image using Gemini AI (gemini-3-pro-image-preview). Pass a prompt and an optional background image as base64. Returns { image_base64, mime_type }.
generate_image
ChatGPTGenerate an image using Gemini AI (gemini-3-pro-image-preview). Pass a prompt and an optional background image as base64. Returns { image_base64, mime_type }.
generate_synthetic_conversations
ChatGPTGenerate synthetic conversations for an agent by invoking the replicant Lambda. Two mutually-exclusive modes: pass personas for AI-simulated leads (user generated by an LLM), or pass scripted_scenarios to replay fixed user messages with no user-side inference (only the agent responds). Fan-out across the chosen items and return conversations in both structured and markdown formats. Returns { conversations, test_run_ids, lambda_invocations, lambda_errors, conversations_fetched, conversations_filtered, elapsed_seconds, warning }. min_turns defaults to 1 in scripted mode and 3 with personas; warning is non-null when every fetched conversation was dropped by min_turns (returned 0), suggesting a lower min_turns. influencer_id is inferred from the JWT when using an influencer-scoped token — only required when using admin or API key auth.
generate_synthetic_conversations
ChatGPTGenerate synthetic conversations for an agent by invoking the replicant Lambda. Two mutually-exclusive modes: pass personas for AI-simulated leads (user generated by an LLM), or pass scripted_scenarios to replay fixed user messages with no user-side inference (only the agent responds). Fan-out across the chosen items and return conversations in both structured and markdown formats. Returns { conversations, test_run_ids, lambda_invocations, lambda_errors, conversations_fetched, conversations_filtered, elapsed_seconds, warning }. min_turns defaults to 1 in scripted mode and 3 with personas; warning is non-null when every fetched conversation was dropped by min_turns (returned 0), suggesting a lower min_turns. influencer_id is inferred from the JWT when using an influencer-scoped token — only required when using admin or API key auth.
get_agent_config
ChatGPTGet the full configuration snapshot for a Ninjo agent: agent metadata, system prompt, and AgentConfig settings. Requires an influencer-scoped JWT. Returns { agent, config }.
get_agent_config
ChatGPTGet the full configuration snapshot for a Ninjo agent: agent metadata, system prompt, and AgentConfig settings. Requires an influencer-scoped JWT. Returns { agent, config }.
get_agent_insights
ChatGPTFetch operational insights snapshot for an agent: quick stats (24h activity), hot leads waiting for follow-up, stalled leads by objection type, funnel transition rates, and content source performance. Returns: - quick_stats: { new_conversations_24h, qualified_leads_24h, bookings_sent_24h } - hot_leads: leads with funnel≥2, lead_score≥3, last message INBOUND 24–72h ago (up to 20) - stalled_by_objection: leads stalled 1–3 funnel, grouped by objection (MONEY/TRUST/TIMING/PRIORITY/UNKNOWN) - funnel_transitions: conversion rates between funnel stages for the lookback period - content_sources: per-source (Organic DM / Story Reply / Ad) conversion performance influencer_id is inferred from the JWT when using an influencer-scoped token.
get_agent_insights
ChatGPTFetch operational insights snapshot for an agent: quick stats (24h activity), hot leads waiting for follow-up, stalled leads by objection type, funnel transition rates, and content source performance. Returns: - quick_stats: { new_conversations_24h, qualified_leads_24h, bookings_sent_24h } - hot_leads: leads with funnel≥2, lead_score≥3, last message INBOUND 24–72h ago (up to 20) - stalled_by_objection: leads stalled 1–3 funnel, grouped by objection (MONEY/TRUST/TIMING/PRIORITY/UNKNOWN) - funnel_transitions: conversion rates between funnel stages for the lookback period - content_sources: per-source (Organic DM / Story Reply / Ad) conversion performance influencer_id is inferred from the JWT when using an influencer-scoped token.
get_agent_metrics
ChatGPTCalculate performance metrics for one or all agents. Includes engagement, funnel, lead score, booking rates, happy path, nurturing quality, monotonicity of funnel progression, and relative risk scores (z-scores). Returns { days, min_leads, agents: [{ influencer_id, influencer_username, leads, avg_engagement_score, avg_funnel, avg_lead_score, funnel_to_lead_score_ratio, bookings_sent, booking_send_rate, call_booked_observed_leads, calls_booked, call_book_rate_total, call_book_rate_per_lead_observed, call_book_rate_per_booking_observed, pct_calls_booked_low_lead_score, avg_happy_path_score, avg_nurturing_score, pct_happy_lt_60, pct_nurture_lt_60, pct_lead_score_eq_1, pct_funnel_ge_4, premature_rate_refined, stages_compared, monotonic_violations, worst_drop, lead_score_monotonic_non_decreasing, risk_raw, risk_score_0_100 }] }.
get_agent_metrics
ChatGPTCalculate performance metrics for one or all agents. Includes engagement, funnel, lead score, booking rates, happy path, nurturing quality, monotonicity of funnel progression, and relative risk scores (z-scores). Returns { days, min_leads, agents: [{ influencer_id, influencer_username, leads, avg_engagement_score, avg_funnel, avg_lead_score, funnel_to_lead_score_ratio, bookings_sent, booking_send_rate, call_booked_observed_leads, calls_booked, call_book_rate_total, call_book_rate_per_lead_observed, call_book_rate_per_booking_observed, pct_calls_booked_low_lead_score, avg_happy_path_score, avg_nurturing_score, pct_happy_lt_60, pct_nurture_lt_60, pct_lead_score_eq_1, pct_funnel_ge_4, premature_rate_refined, stages_compared, monotonic_violations, worst_drop, lead_score_monotonic_non_decreasing, risk_raw, risk_score_0_100 }] }.
get_contact_limits_context
ChatGPTFetch context data required to configure contact limits: available agents and custom properties with options. Returns { agents, customProperties }.
get_contact_limits_context
ChatGPTFetch context data required to configure contact limits: available agents and custom properties with options. Returns { agents, customProperties }.
get_conversations
ChatGPTFetch real production conversations from influencer_conversation_rollup_view_rls + messages table. Returns conversation metadata and full message history. Modes: - recent: latest conversations with ≥3 messages - booking: booking link was shared with the lead - high-funnel: funnel stage ≥ 4 - high-score: Lead Score > 3 - bad: funnel ≥ 4 but lead score ≤ 3 (high funnel, low quality) - low-happy: happy_path_score < 60 - high-happy: happy_path_score ≥ 80 - stuck: agent sent ≥ 6 messages but funnel < 3 influencer_id is inferred from the JWT when using an influencer-scoped token. Returns { influencer_id, mode, count, conversations: [{ conversation_id, contact_id, contact_username, meta: {...}, messages: [{direction, sent_at, content}] }] }. The contact_id can be passed to the WhatsApp template preview/send tools.
get_conversations
ChatGPTFetch real production conversations from influencer_conversation_rollup_view_rls + messages table. Returns conversation metadata and full message history. Modes: - recent: latest conversations with ≥3 messages - booking: booking link was shared with the lead - high-funnel: funnel stage ≥ 4 - high-score: Lead Score > 3 - bad: funnel ≥ 4 but lead score ≤ 3 (high funnel, low quality) - low-happy: happy_path_score < 60 - high-happy: happy_path_score ≥ 80 - stuck: agent sent ≥ 6 messages but funnel < 3 influencer_id is inferred from the JWT when using an influencer-scoped token. Returns { influencer_id, mode, count, conversations: [{ conversation_id, contact_id, contact_username, meta: {...}, messages: [{direction, sent_at, content}] }] }. The contact_id can be passed to the WhatsApp template preview/send tools.
get_instagram_posts
ChatGPTFetch the influencer's recent Instagram posts via Meta Graph API. influencer_id from auth when available; from param when admin.
get_instagram_posts
ChatGPTFetch the influencer's recent Instagram posts via Meta Graph API. influencer_id from auth when available; from param when admin.
get_instagram_profile
ChatGPTFetch the influencer's Instagram profile via Meta Graph API. influencer_id from auth when available; from param when admin.
get_instagram_profile
ChatGPTFetch the influencer's Instagram profile via Meta Graph API. influencer_id from auth when available; from param when admin.
get_knowledge
ChatGPTFetch a specific platform knowledge document by slug. Use list_knowledge first to discover available slugs.
get_knowledge
ChatGPTFetch a specific platform knowledge document by slug. Use list_knowledge first to discover available slugs.
get_me
ChatGPTReturn the current authenticated context: influencer_id (the one active for this request), user_id, scope (single-influencer | multi-influencer | admin), available_influencer_ids (selectable via X-Influencer-Id when the token carries a user_id; multi-influencer + admin tokens), and influencers (map of influencer_id → Instagram handle — identify a creator by handle but pass the influencer_id to tools). 'scope' is the selection mode, NOT a DB role, and does not limit which tools you can call. Same shape as GET /api/v1/me.
get_me
ChatGPTReturn the current authenticated context: influencer_id (the one active for this request), user_id, scope (single-influencer | multi-influencer | admin), available_influencer_ids (selectable via X-Influencer-Id when the token carries a user_id; multi-influencer + admin tokens), and influencers (map of influencer_id → Instagram handle — identify a creator by handle but pass the influencer_id to tools). 'scope' is the selection mode, NOT a DB role, and does not limit which tools you can call. Same shape as GET /api/v1/me.
get_peer_managed_files
ChatGPTReturns managed files (e.g. changelog.md) from peer influencers that share the same use_case or vertical as the requesting influencer. influencer_id from auth when available; from param when admin. At least one of use_case or vertical must be provided. Returns { peers: [...], total }.
get_peer_managed_files
ChatGPTReturns managed files (e.g. changelog.md) from peer influencers that share the same use_case or vertical as the requesting influencer. influencer_id from auth when available; from param when admin. At least one of use_case or vertical must be provided. Returns { peers: [...], total }.
get_playbook_doc
ChatGPTFetch one playbook, template, or worked-example SDK by an id from get_playbook_index. For sample SDKs, call with no section to get the file manifest, then pass section to select a file (e.g. system, examples, objections, keywords, meta). Large docs paginate: when has_more is true, call again with the returned next_cursor.
get_playbook_doc
ChatGPTFetch one playbook, template, or worked-example SDK by an id from get_playbook_index. For sample SDKs, call with no section to get the file manifest, then pass section to select a file (e.g. system, examples, objections, keywords, meta). Large docs paginate: when has_more is true, call again with the returned next_cursor.
get_playbook_index
ChatGPTCall this FIRST before creating, iterating, analyzing, or answering any question about a Ninjo agent or the cortex SDK. Returns the catalog of operating manual, knowledge base, prompt-architecture templates, and worked-example SDKs; fetch the relevant ones with get_playbook_doc before drafting. A Ninjo agent is a SYSTEM (system prompt + the 8 v5Config fields + triggers + automation), not just a prompt — the playbook is how you build the whole system instead of a bare prompt.
get_playbook_index
ChatGPTCall this FIRST before creating, iterating, analyzing, or answering any question about a Ninjo agent or the cortex SDK. Returns the catalog of operating manual, knowledge base, prompt-architecture templates, and worked-example SDKs; fetch the relevant ones with get_playbook_doc before drafting. A Ninjo agent is a SYSTEM (system prompt + the 8 v5Config fields + triggers + automation), not just a prompt — the playbook is how you build the whole system instead of a bare prompt.
get_self_serve_data
ChatGPTFetch self-serve onboarding data from MongoDB for an influencer. Returns data from four collections: - influencer_bio: IG profile processed by GPT (bio, audience, content formats, engagement patterns) - instagram_post: Posts with metrics and video transcriptions - instagram_conversation: DM conversations with followers - creator_input: Self-serve onboarding form (program details, lead magnets, style, use case) Missing sources are listed in missing_sources — expected for incomplete onboarding. Returns { influencer_id, sections: [{ source, count?, data }], missing_sources: string[] }.
get_self_serve_data
ChatGPTFetch self-serve onboarding data from MongoDB for an influencer. Returns data from four collections: - influencer_bio: IG profile processed by GPT (bio, audience, content formats, engagement patterns) - instagram_post: Posts with metrics and video transcriptions - instagram_conversation: DM conversations with followers - creator_input: Self-serve onboarding form (program details, lead magnets, style, use case) Missing sources are listed in missing_sources — expected for incomplete onboarding. Returns { influencer_id, sections: [{ source, count?, data }], missing_sources: string[] }.
get_synthetic_conversations
ChatGPTFetch synthetic conversations from MongoDB by one or more test_run_ids. Use this to retrieve results after a generate_synthetic_conversations call or to re-fetch existing runs. Returns { conversations, count }.
get_synthetic_conversations
ChatGPTFetch synthetic conversations from MongoDB by one or more test_run_ids. Use this to retrieve results after a generate_synthetic_conversations call or to re-fetch existing runs. Returns { conversations, count }.
get_thread_messages
ChatGPTGet message history for a Cortex thread, ordered chronologically. Supports cursor-based pagination via the before parameter (ISO timestamp). Returns { messages: [{ id, role, content, created_at }] }.
get_thread_messages
ChatGPTGet message history for a Cortex thread, ordered chronologically. Supports cursor-based pagination via the before parameter (ISO timestamp). Returns { messages: [{ id, role, content, created_at }] }.
get_trigger_negative_config
ChatGPTGet the negative config (temporary block) of a trigger. When enabled and now < expires_at, the trigger is suppressed even if it would otherwise match. Returns { negative_config } which is null if none is set. trigger_type: keywords | all-messages | comments | ads (outgoing-messages and instagram-story are not supported).
get_trigger_negative_config
ChatGPTGet the negative config (temporary block) of a trigger. When enabled and now < expires_at, the trigger is suppressed even if it would otherwise match. Returns { negative_config } which is null if none is set. trigger_type: keywords | all-messages | comments | ads (outgoing-messages and instagram-story are not supported).
get_workflow_activity
ChatGPTGet workflow activity snapshot (fires/evaluations) for the last N days. Returns { days, since, activity }.
get_workflow_activity
ChatGPTGet workflow activity snapshot (fires/evaluations) for the last N days. Returns { days, since, activity }.
list_agent_tools
ChatGPTList all tools/skills assigned to a Ninjo agent, including their enabled status, settings, and prompt.
list_agent_tools
ChatGPTList all tools/skills assigned to a Ninjo agent, including their enabled status, settings, and prompt.
list_agents
ChatGPTList all agents belonging to the authenticated influencer. Returns { agents: AgentRow[], count: number }. Useful to resolve an agent_id when only the influencer identity is known.
list_agents
ChatGPTList all agents belonging to the authenticated influencer. Returns { agents: AgentRow[], count: number }. Useful to resolve an agent_id when only the influencer identity is known.
list_connected_accounts
ChatGPTList connected Meta sub-accounts linked to a Ninjo agent. Returns { accounts, count }. Metadata only — no access tokens or secrets are returned.
list_connected_accounts
ChatGPTList connected Meta sub-accounts linked to a Ninjo agent. Returns { accounts, count }. Metadata only — no access tokens or secrets are returned.
list_contact_limits
ChatGPTList configured contact limits for an influencer. Returns { contactLimits: ContactLimit[] } including related agents and propertyConditions.
list_contact_limits
ChatGPTList configured contact limits for an influencer. Returns { contactLimits: ContactLimit[] } including related agents and propertyConditions.
list_creator_resources
ChatGPTList the influencer's agent-sendable resources (audio/image clips sent mid-conversation). Filter by type (IMAGE | AUDIO) and agent_usable_only. Returns { resources: [{ id, name, type, agent_usable, agent_usage_context, ... }], count }.
list_creator_resources
ChatGPTList the influencer's agent-sendable resources (audio/image clips sent mid-conversation). Filter by type (IMAGE | AUDIO) and agent_usable_only. Returns { resources: [{ id, name, type, agent_usable, agent_usage_context, ... }], count }.
list_custom_notifications
ChatGPTList custom notifications for an influencer. Includes linked destinations. Returns { customNotifications }.
list_custom_notifications
ChatGPTList custom notifications for an influencer. Includes linked destinations. Returns { customNotifications }.
list_custom_properties
ChatGPTList custom properties for an influencer. Includes rich metadata and options. Returns { customProperties }.
list_custom_properties
ChatGPTList custom properties for an influencer. Includes rich metadata and options. Returns { customProperties }.
list_documents
ChatGPTList all context documents (agent_document_contents) for a Ninjo agent. Returns { documents, count }.
list_documents
ChatGPTList all context documents (agent_document_contents) for a Ninjo agent. Returns { documents, count }.
list_influencer_connected_accounts
ChatGPTList ALL connected Meta sub-accounts that belong to the influencer (Instagram, WhatsApp, etc.), whether or not they are linked to an agent. Use this to DISCOVER the connected_account_id to pass to set_connected_account when linking a fresh agent — list_connected_accounts only shows accounts already linked to a given agent, so it is empty for a new agent. Returns { accounts, count }. Metadata only — no access tokens or secrets are returned.
list_influencer_connected_accounts
ChatGPTList ALL connected Meta sub-accounts that belong to the influencer (Instagram, WhatsApp, etc.), whether or not they are linked to an agent. Use this to DISCOVER the connected_account_id to pass to set_connected_account when linking a fresh agent — list_connected_accounts only shows accounts already linked to a given agent, so it is empty for a new agent. Returns { accounts, count }. Metadata only — no access tokens or secrets are returned.
list_knowledge
ChatGPTList all available platform knowledge documents (playbooks, templates, strategy guides, platform docs). Returns slug, category, and title for each doc. Use get_knowledge with a slug to fetch the full content.
list_knowledge
ChatGPTList all available platform knowledge documents (playbooks, templates, strategy guides, platform docs). Returns slug, category, and title for each doc. Use get_knowledge with a slug to fetch the full content.
list_notification_destinations
ChatGPTList custom notification destinations for an influencer. Optional channel filter. Returns { notificationDestinations }.
list_notification_destinations
ChatGPTList custom notification destinations for an influencer. Optional channel filter. Returns { notificationDestinations }.
list_threads
ChatGPTList Cortex threads for an influencer, ordered by most recently updated. Each item includes id, title, status, last_message, created_at, updated_at.
list_threads
ChatGPTList Cortex threads for an influencer, ordered by most recently updated. Each item includes id, title, status, last_message, created_at, updated_at.
list_trigger_audios
ChatGPTList the audios attached to a trigger, ordered by order ascending. type selects which trigger family: keywords (DM keyword trigger) or ads (ad referral trigger). Each audio references a CreatorResource (type=AUDIO) played in rotation when the trigger matches. Returns { audios }.
list_trigger_audios
ChatGPTList the audios attached to a trigger, ordered by order ascending. type selects which trigger family: keywords (DM keyword trigger) or ads (ad referral trigger). Each audio references a CreatorResource (type=AUDIO) played in rotation when the trigger matches. Returns { audios }.
list_trigger_canned_responses
ChatGPTList the canned text response variants configured on a trigger, ordered by order ascending. On the FIRST trigger match in a conversation, mk1-chat sends one variant at random instead of invoking the LLM (saving agent cost); follow-up messages are handled by the normal agent. type selects the trigger family: keywords | all-messages | comments | ads | instagram-story (outgoing-messages is not supported). Returns { canned_responses }.
list_trigger_canned_responses
ChatGPTList the canned text response variants configured on a trigger, ordered by order ascending. On the FIRST trigger match in a conversation, mk1-chat sends one variant at random instead of invoking the LLM (saving agent cost); follow-up messages are handled by the normal agent. type selects the trigger family: keywords | all-messages | comments | ads | instagram-story (outgoing-messages is not supported). Returns { canned_responses }.
list_triggers
ChatGPTList all triggers for a Ninjo agent, grouped by type: keywords (DM keyword triggers), all_messages (ALL_DM / ALL_COMMENTS), comments (comment keyword triggers), ads (ad referral triggers), outgoing_messages, instagram_story. Keyword and ad referral triggers include audios when configured.
list_triggers
ChatGPTList all triggers for a Ninjo agent, grouped by type: keywords (DM keyword triggers), all_messages (ALL_DM / ALL_COMMENTS), comments (comment keyword triggers), ads (ad referral triggers), outgoing_messages, instagram_story. Keyword and ad referral triggers include audios when configured.
list_whatsapp_template_definitions
ChatGPTList the influencer's stored WhatsApp template definitions (via mk1-chat). A template definition is the persisted binding that a WHATSAPP_TEMPLATE notification destination points at (whatsappTemplateDefinitionId). Use this to obtain that UUID when wiring upsert_notification_destination, or to inspect the current variable values. Returns { ok, influencerId, definitions: [{ id, templateId, templateName, languageCode, variableMappings: [{ id, name, value, locations }] }], count }.
list_whatsapp_template_definitions
ChatGPTList the influencer's stored WhatsApp template definitions (via mk1-chat). A template definition is the persisted binding that a WHATSAPP_TEMPLATE notification destination points at (whatsappTemplateDefinitionId). Use this to obtain that UUID when wiring upsert_notification_destination, or to inspect the current variable values. Returns { ok, influencerId, definitions: [{ id, templateId, templateName, languageCode, variableMappings: [{ id, name, value, locations }] }], count }.
list_whatsapp_templates
ChatGPTList the influencer's Meta-approved WhatsApp message templates (via mk1-chat). Use this first when the user wants to start a WhatsApp conversation outside the 24-hour customer-service window — only APPROVED templates can be sent. Returns { ok, influencerId, templates: [{ templateId, name, language, status, components }], count }.
list_whatsapp_templates
ChatGPTList the influencer's Meta-approved WhatsApp message templates (via mk1-chat). Use this first when the user wants to start a WhatsApp conversation outside the 24-hour customer-service window — only APPROVED templates can be sent. Returns { ok, influencerId, templates: [{ templateId, name, language, status, components }], count }.
list_workflows
ChatGPTList workflows for an influencer. Optional filters: type and customNotificationId. Returns { workflows }.
list_workflows
ChatGPTList workflows for an influencer. Optional filters: type and customNotificationId. Returns { workflows }.
pause_conversation_agent
ChatGPTPause the agent on a specific conversation. The agent will stop responding to inbound messages in that conversation until resumed. Identify the conversation by the contact's platform identifier (Instagram username, Facebook ID, or WhatsApp phone number).
pause_conversation_agent
ChatGPTPause the agent on a specific conversation. The agent will stop responding to inbound messages in that conversation until resumed. Identify the conversation by the contact's platform identifier (Instagram username, Facebook ID, or WhatsApp phone number).
preview_whatsapp_template_recipients
ChatGPTResolve candidate contact ids server-side before sending a WhatsApp template. Contacts without a WhatsApp number or unsubscribed from WhatsApp are excluded. ALWAYS call this before send_whatsapp_template: show the eligible sample and counts to the user and obtain their explicit confirmation. Then send with the SAME contactIds you previewed. Returns { ok, influencerId, requestedCount, eligibleCount, excludedCount, eligibleSample, eligibleSampleTruncated, eligibleSampleLimit, excludedContactIds }.
preview_whatsapp_template_recipients
ChatGPTResolve candidate contact ids server-side before sending a WhatsApp template. Contacts without a WhatsApp number or unsubscribed from WhatsApp are excluded. ALWAYS call this before send_whatsapp_template: show the eligible sample and counts to the user and obtain their explicit confirmation. Then send with the SAME contactIds you previewed. Returns { ok, influencerId, requestedCount, eligibleCount, excludedCount, eligibleSample, eligibleSampleTruncated, eligibleSampleLimit, excludedContactIds }.
register_creator_resource
ChatGPTStep 2 of uploading: after PUTting the file to the presigned URL, register the DB row pointing at s3_key and make it agent-usable. usage_context is required when agent_usable is true (the default) — a concrete sentence telling the agent WHEN to send it. Returns { resource }.
register_creator_resource
ChatGPTStep 2 of uploading: after PUTting the file to the presigned URL, register the DB row pointing at s3_key and make it agent-usable. usage_context is required when agent_usable is true (the default) — a concrete sentence telling the agent WHEN to send it. Returns { resource }.
replace_objectives
ChatGPTReplace all objectives for a Ninjo agent. Deletes existing objectives and inserts the provided array. Pass an empty array to clear all objectives. Returns { success: true }.
replace_objectives
ChatGPTReplace all objectives for a Ninjo agent. Deletes existing objectives and inserts the provided array. Pass an empty array to clear all objectives. Returns { success: true }.
report_feedback
ChatGPTReport a problem to the Ninjo developers when you cannot complete a task (missing tool/skill/playbook/info, a bug, or a feature request). Files an issue in Linear (Cortex-ops project, label by type: ERROR→Bug, FEATURE_REQUEST→Feature, MISSING_INFO→Improvement) and pings the devs Slack channel with the ticket + affected client. Provide what you were trying to do (operation), what went wrong (problem), and the type. To attach the full session, first call create_feedback_upload_url, upload the session, and pass its s3_key as session_s3_key. Returns { ok, issue_id, issue_identifier, issue_url, slack_posted }. slack_posted may be false (partial success) even when the issue was created.
report_feedback
ChatGPTReport a problem to the Ninjo developers when you cannot complete a task (missing tool/skill/playbook/info, a bug, or a feature request). Files an issue in Linear (Cortex-ops project, label by type: ERROR→Bug, FEATURE_REQUEST→Feature, MISSING_INFO→Improvement) and pings the devs Slack channel with the ticket + affected client. Provide what you were trying to do (operation), what went wrong (problem), and the type. To attach the full session, first call create_feedback_upload_url, upload the session, and pass its s3_key as session_s3_key. Returns { ok, issue_id, issue_identifier, issue_url, slack_posted }. slack_posted may be false (partial success) even when the issue was created.
restore_prompt_version
ChatGPTRestore a previous prompt version. Sets the agent's active prompt to the specified version and updates current_prompt_version_id.
restore_prompt_version
ChatGPTRestore a previous prompt version. Sets the agent's active prompt to the specified version and updates current_prompt_version_id.
resume_conversation_agent
ChatGPTResume the agent on a previously paused conversation. The agent will start responding to inbound messages again. Identify the conversation by the contact's platform identifier (Instagram username, Facebook ID, or WhatsApp phone number).
resume_conversation_agent
ChatGPTResume the agent on a previously paused conversation. The agent will start responding to inbound messages again. Identify the conversation by the contact's platform identifier (Instagram username, Facebook ID, or WhatsApp phone number).
save_image
ChatGPTUpload a base64 image to S3 (ninjo-prod-content, key: amplify/campaigns/{campaign_id}/{sequence}.{ext}) and update campaign_sections.image_url in the database. Returns { cdn_url }.
save_image
ChatGPTUpload a base64 image to S3 (ninjo-prod-content, key: amplify/campaigns/{campaign_id}/{sequence}.{ext}) and update campaign_sections.image_url in the database. Returns { cdn_url }.
scaffold_agent_activation
ChatGPTWire the standard activation kit onto an agent, correct-by-construction. diagnose_agent DETECTS missing activation infra; this REMEDIATES it. The gateway can't infer an agent's conversion property or motion, so you supply the intent and this guarantees correct wiring: - ensures terminal_property exists as a BOOLEAN (string properties gate unreliably), - an enabled contact limit gated on it, so the agent stops messaging contacts who converted, - (followup) a FOLLOW_UP gated on not-converted (+ optional interest) — never ungated, - (notify) a conversion notification (workflow + custom notification) on an existing destination. Idempotent: re-running reuses any piece already wired for this agent instead of duplicating it. Returns what was created vs reused, plus a fresh completeness report. NOTE: if terminal_property is not a recognized terminal codename (call_booked / purchased / …), diagnose may still report no_terminal_stop — recognized_terminal in the result tells you.
scaffold_agent_activation
ChatGPTWire the standard activation kit onto an agent, correct-by-construction. diagnose_agent DETECTS missing activation infra; this REMEDIATES it. The gateway can't infer an agent's conversion property or motion, so you supply the intent and this guarantees correct wiring: - ensures terminal_property exists as a BOOLEAN (string properties gate unreliably), - an enabled contact limit gated on it, so the agent stops messaging contacts who converted, - (followup) a FOLLOW_UP gated on not-converted (+ optional interest) — never ungated, - (notify) a conversion notification (workflow + custom notification) on an existing destination. Idempotent: re-running reuses any piece already wired for this agent instead of duplicating it. Returns what was created vs reused, plus a fresh completeness report. NOTE: if terminal_property is not a recognized terminal codename (call_booked / purchased / …), diagnose may still report no_terminal_stop — recognized_terminal in the result tells you.
search_contacts
ChatGPTSearch the influencer's contact directory with composable AND filters and pagination — the same audience picker behind the studio contacts/templates page. Returns each contact's contact_id, which you pass to preview_whatsapp_template_recipients and send_whatsapp_template. Native filters (all optional): name (partial, first or last), email, phone, whatsapp_number, instagram_username, is_whatsapp_subscribed, has_whatsapp_number, created_after / created_before (ISO 8601). Ad attribution: from_ads (true → only contacts who came from a Meta ad — at least one inbound Instagram/Facebook message carries an ad referral; false → only contacts with no ad referral on any inbound), ad_id (only contacts with an inbound referral for that exact Meta ad id; implies from_ads). When either is set, each contact is enriched with its first-touch ad metadata — the earliest ad-tagged inbound — (referral_ad_id, referral_source, referral_type, referral_ref, ad_title, ad_post_id, ad_photo_url, ad_video_url, post_url); otherwise those fields come back null. Custom-property filters (custom_properties[]): each { codename, ... } is resolved to the property's type and matched accordingly: - boolean → equals_boolean - integer → min and/or max - option → value (the option's text, case-insensitive) - string → value (case-insensitive contains) Get codenames from list_custom_properties. Pagination: limit (default 25, max 100), page (default 1). To target a WhatsApp template send: filter here (often is_whatsapp_subscribed: true + has_whatsapp_number: true), collect contact_id values, then preview before sending. Preview re-applies eligibility server-side, so search is for audience selection, not the final eligibility gate. Returns { influencer_id, filters_applied, total_count, page, total_pages, pages_remaining, count, contacts: [{ contact_id, first_name, last_name, email, phone_number, whatsapp_number, is_whatsapp_subscribed, instagram_username, created_at, referral_ad_id, referral_source, referral_type, referral_ref, ad_title, ad_post_id, ad_photo_url, ad_video_url, post_url }] }.
search_contacts
ChatGPTSearch the influencer's contact directory with composable AND filters and pagination — the same audience picker behind the studio contacts/templates page. Returns each contact's contact_id, which you pass to preview_whatsapp_template_recipients and send_whatsapp_template. Native filters (all optional): name (partial, first or last), email, phone, whatsapp_number, instagram_username, is_whatsapp_subscribed, has_whatsapp_number, created_after / created_before (ISO 8601). Ad attribution: from_ads (true → only contacts who came from a Meta ad — at least one inbound Instagram/Facebook message carries an ad referral; false → only contacts with no ad referral on any inbound), ad_id (only contacts with an inbound referral for that exact Meta ad id; implies from_ads). When either is set, each contact is enriched with its first-touch ad metadata — the earliest ad-tagged inbound — (referral_ad_id, referral_source, referral_type, referral_ref, ad_title, ad_post_id, ad_photo_url, ad_video_url, post_url); otherwise those fields come back null. Custom-property filters (custom_properties[]): each { codename, ... } is resolved to the property's type and matched accordingly: - boolean → equals_boolean - integer → min and/or max - option → value (the option's text, case-insensitive) - string → value (case-insensitive contains) Get codenames from list_custom_properties. Pagination: limit (default 25, max 100), page (default 1). To target a WhatsApp template send: filter here (often is_whatsapp_subscribed: true + has_whatsapp_number: true), collect contact_id values, then preview before sending. Preview re-applies eligibility server-side, so search is for audience selection, not the final eligibility gate. Returns { influencer_id, filters_applied, total_count, page, total_pages, pages_remaining, count, contacts: [{ contact_id, first_name, last_name, email, phone_number, whatsapp_number, is_whatsapp_subscribed, instagram_username, created_at, referral_ad_id, referral_source, referral_type, referral_ref, ad_title, ad_post_id, ad_photo_url, ad_video_url, post_url }] }.
search_conversations
ChatGPTSearch real production conversations from influencer_conversation_rollup_view_rls + messages table using composable AND filters, with pagination. Returns conversation metadata and full message history. Unlike get_conversations (curated modes), this has NO implicit minimum message count — pass min_messages: 3 to reproduce the "recent" behavior. Omitting all filters returns every agent conversation for the influencer. Filters (all optional, combined with AND): - conversation_id: exact match — returns that single conversation - contact_username: case-insensitive partial match on the contact identifier (instagram/tiktok handle, phone, whatsapp) - messages/funnel: min_messages, max_messages, min_agent_messages, min_funnel, max_funnel - scores: min_lead_score, max_lead_score, min_happy_path, max_happy_path, min_nurturing, max_nurturing, min_engagement, max_engagement - booleans: has_booking_link, is_lead, call_booked, open_conversation - date ranges (ISO 8601): last_message_after, last_message_before, first_message_after, first_message_before - pagination: limit (default 10, max 100), page (default 1) influencer_id is inferred from the JWT when using an influencer-scoped token. Returns { influencer_id, filters_applied, total_count, page, total_pages, pages_remaining, count, conversations: [{ conversation_id, contact_id, contact_username, meta, messages }] }. The contact_id can be passed to the WhatsApp template preview/send tools.
search_conversations
ChatGPTSearch real production conversations from influencer_conversation_rollup_view_rls + messages table using composable AND filters, with pagination. Returns conversation metadata and full message history. Unlike get_conversations (curated modes), this has NO implicit minimum message count — pass min_messages: 3 to reproduce the "recent" behavior. Omitting all filters returns every agent conversation for the influencer. Filters (all optional, combined with AND): - conversation_id: exact match — returns that single conversation - contact_username: case-insensitive partial match on the contact identifier (instagram/tiktok handle, phone, whatsapp) - messages/funnel: min_messages, max_messages, min_agent_messages, min_funnel, max_funnel - scores: min_lead_score, max_lead_score, min_happy_path, max_happy_path, min_nurturing, max_nurturing, min_engagement, max_engagement - booleans: has_booking_link, is_lead, call_booked, open_conversation - date ranges (ISO 8601): last_message_after, last_message_before, first_message_after, first_message_before - pagination: limit (default 10, max 100), page (default 1) influencer_id is inferred from the JWT when using an influencer-scoped token. Returns { influencer_id, filters_applied, total_count, page, total_pages, pages_remaining, count, conversations: [{ conversation_id, contact_id, contact_username, meta, messages }] }. The contact_id can be passed to the WhatsApp template preview/send tools.
search_playbook
ChatGPTSearch the playbook for relevant passages instead of fetching whole docs; returns ranked snippets with the id (and section for samples) you can pass to get_playbook_doc to read more. Use get_playbook_index first to understand the catalog.
search_playbook
ChatGPTSearch the playbook for relevant passages instead of fetching whole docs; returns ranked snippets with the id (and section for samples) you can pass to get_playbook_doc to read more. Use get_playbook_index first to understand the catalog.
send_thread_message
ChatGPTSend a message to a Cortex thread. The request is accepted immediately (202) and processed asynchronously — the agent response is inserted once OpenClaw responds. Returns { message_id }.
send_thread_message
ChatGPTSend a message to a Cortex thread. The request is accepted immediately (202) and processed asynchronously — the agent response is inserted once OpenClaw responds. Returns { message_id }.
send_whatsapp_template
ChatGPTSend a Meta-approved WhatsApp template to one or more contacts (via mk1-chat). HIGH IMPACT: this delivers real WhatsApp messages, billed by Meta. MANDATORY workflow — never skip a step: 1. list_whatsapp_templates — discover APPROVED templates 2. preview_whatsapp_template_recipients — resolve eligible recipients 3. Show the user the eligible sample/counts and ask for explicit confirmation 4. Call this tool with userConfirmed: true and the SAME contactIds you previewed Returns { ok, influencerId, templateId, createdCount, skippedCount, totalContacts }.
send_whatsapp_template
ChatGPTSend a Meta-approved WhatsApp template to one or more contacts (via mk1-chat). HIGH IMPACT: this delivers real WhatsApp messages, billed by Meta. MANDATORY workflow — never skip a step: 1. list_whatsapp_templates — discover APPROVED templates 2. preview_whatsapp_template_recipients — resolve eligible recipients 3. Show the user the eligible sample/counts and ask for explicit confirmation 4. Call this tool with userConfirmed: true and the SAME contactIds you previewed Returns { ok, influencerId, templateId, createdCount, skippedCount, totalContacts }.
set_agent_status
ChatGPTEnable or disable a Ninjo agent by setting is_active. Requires an influencer-scoped JWT. Returns { success: true }.
set_agent_status
ChatGPTEnable or disable a Ninjo agent by setting is_active. Requires an influencer-scoped JWT. Returns { success: true }.
set_connected_account
ChatGPTLink or unlink a connected Meta sub-account to/from a Ninjo agent (many-to-many). Pass connected_account_id to ADD a link (leaves existing links intact), or null to unlink ALL sub-accounts from this agent. Returns { success: true }.
set_connected_account
ChatGPTLink or unlink a connected Meta sub-account to/from a Ninjo agent (many-to-many). Pass connected_account_id to ADD a link (leaves existing links intact), or null to unlink ALL sub-accounts from this agent. Returns { success: true }.
sync_keyword_triggers
ChatGPTReconcile the agent's DM keyword triggers with the provided list using a diff: existing keywords are preserved (created_at untouched), match_mode is patched when it differs, new keywords are inserted, and keywords absent from the input are deleted. Inputs are lowercased + trimmed + deduplicated before diffing. match_type values (SDK format): any_mention/anywhere → ANYWHERE, isolated_word/keyword_only → KEYWORD_ONLY. Returns { deleted, created, updated, keywords } where keywords is the final state sorted alphabetically.
sync_keyword_triggers
ChatGPTReconcile the agent's DM keyword triggers with the provided list using a diff: existing keywords are preserved (created_at untouched), match_mode is patched when it differs, new keywords are inserted, and keywords absent from the input are deleted. Inputs are lowercased + trimmed + deduplicated before diffing. match_type values (SDK format): any_mention/anywhere → ANYWHERE, isolated_word/keyword_only → KEYWORD_ONLY. Returns { deleted, created, updated, keywords } where keywords is the final state sorted alphabetically.
sync_trigger_audios
ChatGPTReconcile the audios attached to a trigger with the provided list: kept audios preserve their row (and created_at), reordered audios get their order patched, new ones are inserted, and ones absent from the input are deleted. type selects the trigger family: keywords or ads. Input is deduplicated by resource_id. Each resource_id must reference a CreatorResource of type AUDIO owned by this influencer — creation/upload of CreatorResources is handled elsewhere. If order is omitted for an item it defaults to the item's index. Returns { deleted, created, updated, audios } where audios is the final list sorted by order.
sync_trigger_audios
ChatGPTReconcile the audios attached to a trigger with the provided list: kept audios preserve their row (and created_at), reordered audios get their order patched, new ones are inserted, and ones absent from the input are deleted. type selects the trigger family: keywords or ads. Input is deduplicated by resource_id. Each resource_id must reference a CreatorResource of type AUDIO owned by this influencer — creation/upload of CreatorResources is handled elsewhere. If order is omitted for an item it defaults to the item's index. Returns { deleted, created, updated, audios } where audios is the final list sorted by order.
sync_trigger_canned_responses
ChatGPTReplace the canned text response variants of a trigger with the provided list, via diff by id: items WITH an existing id update that row in place (text/order), items WITHOUT an id are inserted as new variants, and existing variants absent from the input are deleted. Pass an empty list to remove all variants. To edit safely, call list_trigger_canned_responses first and resend items with their ids. Max 10 variants per trigger; each text is trimmed, must be non-empty and at most 950 characters. If order is omitted for an item it defaults to the item's index. Rejected (400) while the trigger's negative config is enabled — negative triggers cannot carry canned responses. type: keywords | all-messages | comments | ads | instagram-story. Returns { deleted, created, updated, canned_responses } with the final state sorted by order.
sync_trigger_canned_responses
ChatGPTReplace the canned text response variants of a trigger with the provided list, via diff by id: items WITH an existing id update that row in place (text/order), items WITHOUT an id are inserted as new variants, and existing variants absent from the input are deleted. Pass an empty list to remove all variants. To edit safely, call list_trigger_canned_responses first and resend items with their ids. Max 10 variants per trigger; each text is trimmed, must be non-empty and at most 950 characters. If order is omitted for an item it defaults to the item's index. Rejected (400) while the trigger's negative config is enabled — negative triggers cannot carry canned responses. type: keywords | all-messages | comments | ads | instagram-story. Returns { deleted, created, updated, canned_responses } with the final state sorted by order.
trigger_fetch_info
ChatGPTEnsure MongoDB has the influencer's Instagram data by triggering the fetch-info Step Function if needed. Workflow: 1. Checks if influencer_bio already exists in MongoDB → returns status: skipped if yes (unless force=true) 2. Verifies Instagram is connected (access token present in Postgres) 3. Starts the fetch-info Step Function and polls until completion (up to timeout_seconds) 4. Returns the final status Returns { status: "skipped"|"no_ig_connected"|"no_sf_arn"|"succeeded"|"failed"|"timed_out", reason?, execution_arn?, bio_existed? }.
trigger_fetch_info
ChatGPTEnsure MongoDB has the influencer's Instagram data by triggering the fetch-info Step Function if needed. Workflow: 1. Checks if influencer_bio already exists in MongoDB → returns status: skipped if yes (unless force=true) 2. Verifies Instagram is connected (access token present in Postgres) 3. Starts the fetch-info Step Function and polls until completion (up to timeout_seconds) 4. Returns the final status Returns { status: "skipped"|"no_ig_connected"|"no_sf_arn"|"succeeded"|"failed"|"timed_out", reason?, execution_arn?, bio_existed? }.
update_agent
ChatGPTUpdate basic fields on a Ninjo agent: name and/or description. Requires an influencer-scoped JWT. Returns { success: true }.
update_agent
ChatGPTUpdate basic fields on a Ninjo agent: name and/or description. Requires an influencer-scoped JWT. Returns { success: true }.
update_agent_config
ChatGPTUpdate AgentConfig settings. All fields are optional. model, temperature, conversation_summary_enabled, should_respond_check_enabled, is_test_agent, response_filter go into the config JSON. set_on_conversation goes to the agents table. All other fields update agent_configs directly. response_filter tunes the CoT reasoning-leak filter (config.responseFilter): { enabled, extra_patterns (extra JS-regex patterns to strip, additive), disabled_defaults (default patterns to drop for this agent) } — PATCH-merged, so pass only what you change.
update_agent_config
ChatGPTUpdate AgentConfig settings. All fields are optional. model, temperature, conversation_summary_enabled, should_respond_check_enabled, is_test_agent, response_filter go into the config JSON. set_on_conversation goes to the agents table. All other fields update agent_configs directly. response_filter tunes the CoT reasoning-leak filter (config.responseFilter): { enabled, extra_patterns (extra JS-regex patterns to strip, additive), disabled_defaults (default patterns to drop for this agent) } — PATCH-merged, so pass only what you change.
update_agent_mode
ChatGPTUpdate a Ninjo agent's mode and workflow relations. For non-INDIVIDUAL modes, workflow_agents is required. Each workflow_agent must be a valid UUID and cannot be the same as agent_id. Returns { success: true }.
update_agent_mode
ChatGPTUpdate a Ninjo agent's mode and workflow relations. For non-INDIVIDUAL modes, workflow_agents is required. Each workflow_agent must be a valid UUID and cannot be the same as agent_id. Returns { success: true }.
update_agent_voice
ChatGPTUpdate voice reply configuration for a Ninjo agent. All fields are optional and merged into the existing voiceReply config JSON. Returns { success: true }.
update_agent_voice
ChatGPTUpdate voice reply configuration for a Ninjo agent. All fields are optional and merged into the existing voiceReply config JSON. Returns { success: true }.
update_creator_resource
ChatGPTUpdate an existing creator resource's name or agent metadata (agent_usable, usage_context, caption_guidance). PATCH semantics — omitted fields are left untouched. Returns { resource }.
update_creator_resource
ChatGPTUpdate an existing creator resource's name or agent metadata (agent_usable, usage_context, caption_guidance). PATCH semantics — omitted fields are left untouched. Returns { resource }.
update_managed_file
ChatGPTWrite a managed file to influencer_managed_files. influencer_id from auth when available; from param when admin. filepath is relative (e.g. 'changelog.md'). Returns { filepath, content_sha256, updated_at }.
update_managed_file
ChatGPTWrite a managed file to influencer_managed_files. influencer_id from auth when available; from param when admin. filepath is relative (e.g. 'changelog.md'). Returns { filepath, content_sha256, updated_at }.
update_prompt
ChatGPTUpdate the system prompt for a Ninjo agent. Automatically creates a new prompt version and sets it as current. Returns { agent_config_id, prompt_version_id, version }.
update_prompt
ChatGPTUpdate the system prompt for a Ninjo agent. Automatically creates a new prompt version and sets it as current. Returns { agent_config_id, prompt_version_id, version }.
update_resource_sending
ChatGPTEnable/configure the agent sending creator-uploaded audio/image clips mid-conversation (config.resourceSending). enabled toggles the feature; allowed_types is a subset of [IMAGE, AUDIO] (only these are deliverable); max_per_conversation caps how many times the same resource is sent per conversation. PATCH semantics — omitted fields are left untouched. This does NOT create a new prompt version. Returns the merged resourceSending config.
update_resource_sending
ChatGPTEnable/configure the agent sending creator-uploaded audio/image clips mid-conversation (config.resourceSending). enabled toggles the feature; allowed_types is a subset of [IMAGE, AUDIO] (only these are deliverable); max_per_conversation caps how many times the same resource is sent per conversation. PATCH semantics — omitted fields are left untouched. This does NOT create a new prompt version. Returns the merged resourceSending config.
update_tool
ChatGPTUpdate an agent tool. Only allowed fields: enabled (boolean), settings (object), prompt (string). credentials are never modifiable via this tool. Returns { success: true }.
update_tool
ChatGPTUpdate an agent tool. Only allowed fields: enabled (boolean), settings (object), prompt (string). credentials are never modifiable via this tool. Returns { success: true }.
update_trigger
ChatGPTUpdate an existing trigger. type selects the variant: keywords (keyword, match_mode, allow_typo) or outgoing-messages (keyword, assign_unpaused). Only provided fields change. NOTE: for keyword changes that must stay in sync with v5Config, prefer deploy_agent_sdk or sync_keyword_triggers — a single-row keyword edit here does not update v5Config.keywords. Returns { success: true }.
update_trigger
ChatGPTUpdate an existing trigger. type selects the variant: keywords (keyword, match_mode, allow_typo) or outgoing-messages (keyword, assign_unpaused). Only provided fields change. NOTE: for keyword changes that must stay in sync with v5Config, prefer deploy_agent_sdk or sync_keyword_triggers — a single-row keyword edit here does not update v5Config.keywords. Returns { success: true }.
update_v5_config
ChatGPTUpdate the v5Config (Cortex SDK) for an agent. Each field is a text blob that maps to an SDK file (knowledge_base.md, examples.md, etc.). Only the keys you provide are merged; others are preserved. Returns the merged config.
update_v5_config
ChatGPTUpdate the v5Config (Cortex SDK) for an agent. Each field is a text blob that maps to an SDK file (knowledge_base.md, examples.md, etc.). Only the keys you provide are merged; others are preserved. Returns the merged config.
upsert_contact_limit
ChatGPTCreate or update a contact limit — the lever that STOPS an agent from messaging a contact once a terminal state is reached (e.g. they booked a call or purchased). Gate it on a custom property via propertyConditions: this is how you silence the agent after a conversion so the operator stops babysitting DMs by hand. Pass id to update an existing limit; omit id to create a new one. Returns { success: true, contactLimit }.
upsert_contact_limit
ChatGPTCreate or update a contact limit — the lever that STOPS an agent from messaging a contact once a terminal state is reached (e.g. they booked a call or purchased). Gate it on a custom property via propertyConditions: this is how you silence the agent after a conversion so the operator stops babysitting DMs by hand. Pass id to update an existing limit; omit id to create a new one. Returns { success: true, contactLimit }.
upsert_custom_notification
ChatGPTCreate or update a custom notification — alerts the operator the moment something happens (e.g. a lead booked a call). Pair it with a workflow (type CUSTOM_NOTIFICATION) or a contact limit, gated on the custom property that marks the event, so the operator is pinged automatically instead of watching DMs by hand. Pass id to update; omit id to create. Returns { success: true, customNotification }.
upsert_custom_notification
ChatGPTCreate or update a custom notification — alerts the operator the moment something happens (e.g. a lead booked a call). Pair it with a workflow (type CUSTOM_NOTIFICATION) or a contact limit, gated on the custom property that marks the event, so the operator is pinged automatically instead of watching DMs by hand. Pass id to update; omit id to create. Returns { success: true, customNotification }.
upsert_custom_property
ChatGPTCreate or update a custom property. Pass id to update, omit id to create. A property is INERT on its own: an external evaluator fills its value, but nothing happens until a contact limit, custom notification, or workflow CONSUMES it via a propertyCondition — defining the property is only half the job. For any property you will gate automation on (a booking flag, a funnel stage), use a boolean or number type, NOT a string: "true"/"false" string values compare unreliably in conditions. Returns { success: true, customProperty }.
upsert_custom_property
ChatGPTCreate or update a custom property. Pass id to update, omit id to create. A property is INERT on its own: an external evaluator fills its value, but nothing happens until a contact limit, custom notification, or workflow CONSUMES it via a propertyCondition — defining the property is only half the job. For any property you will gate automation on (a booking flag, a funnel stage), use a boolean or number type, NOT a string: "true"/"false" string values compare unreliably in conditions. Returns { success: true, customProperty }.
upsert_notification_destination
ChatGPTCreate or update a notification destination. Pass id to update; omit id to create. Returns { success: true, notificationDestination }.
upsert_notification_destination
ChatGPTCreate or update a notification destination. Pass id to update; omit id to create. Returns { success: true, notificationDestination }.
upsert_trigger_negative_config
ChatGPTCreate or update the negative config (temporary block) of a trigger. The trigger is suppressed while enabled=true AND now < expires_at. A null or past expires_at means the block is effectively inactive even if enabled; for an 'indefinite' block, pass a far-future expires_at (mk1-chat UI uses +100 years). Setting enabled=false clears activated_at. user_timezone is informational (IANA tz). Returns the upserted config.
upsert_trigger_negative_config
ChatGPTCreate or update the negative config (temporary block) of a trigger. The trigger is suppressed while enabled=true AND now < expires_at. A null or past expires_at means the block is effectively inactive even if enabled; for an 'indefinite' block, pass a far-future expires_at (mk1-chat UI uses +100 years). Setting enabled=false clears activated_at. user_timezone is informational (IANA tz). Returns the upserted config.
upsert_whatsapp_template_definition
ChatGPTCreate or update a WhatsApp template definition and its variable bindings (via mk1-chat). Returns the UUID consumed by upsert_notification_destination (whatsappTemplateDefinitionId), closing the workflow-driven outbound WhatsApp path end-to-end via MCP. Identity is the natural key (templateId, influencerId): omit id to create-or-update by that key; pass id to assert you are updating a specific existing definition. mk1-chat rebuilds the full template structure (components/buttons) from the live Meta template — you only supply variable values via variableMappings (an id→value map). templateName/languageCode default to the Meta template when omitted. To discover the variable ids of a new template, call this once with no/partial variableMappings and read them from the returned definition.variableMappings, then call again with the id→value map. Returns { ok, influencerId, created, definition: { id, templateId, templateName, languageCode, variableMappings } }.
upsert_whatsapp_template_definition
ChatGPTCreate or update a WhatsApp template definition and its variable bindings (via mk1-chat). Returns the UUID consumed by upsert_notification_destination (whatsappTemplateDefinitionId), closing the workflow-driven outbound WhatsApp path end-to-end via MCP. Identity is the natural key (templateId, influencerId): omit id to create-or-update by that key; pass id to assert you are updating a specific existing definition. mk1-chat rebuilds the full template structure (components/buttons) from the live Meta template — you only supply variable values via variableMappings (an id→value map). templateName/languageCode default to the Meta template when omitted. To discover the variable ids of a new template, call this once with no/partial variableMappings and read them from the returned definition.variableMappings, then call again with the id→value map. Returns { ok, influencerId, created, definition: { id, templateId, templateName, languageCode, variableMappings } }.
upsert_workflow
ChatGPTCreate or update a workflow — scheduled automation that runs OFF custom properties. The most common use is re-engaging stalled leads: type FOLLOW_UP with a propertyCondition on a funnel/stage property re-nudges contacts who went quiet (a prompt alone never follows up). Other types: CUSTOM_NOTIFICATION (alert the operator), SCHEDULE_REMINDER, CUSTOM_ACTION. Pass id to update; omit id to create. Returns { success: true, workflow }.
upsert_workflow
ChatGPTCreate or update a workflow — scheduled automation that runs OFF custom properties. The most common use is re-engaging stalled leads: type FOLLOW_UP with a propertyCondition on a funnel/stage property re-nudges contacts who went quiet (a prompt alone never follows up). Other types: CUSTOM_NOTIFICATION (alert the operator), SCHEDULE_REMINDER, CUSTOM_ACTION. Pass id to update; omit id to create. Returns { success: true, workflow }.
