Agent API Documentation

This documentation provides details on how to use the Agent API to create, manage, and chat with AI agents.

Base URL

All endpoints are prefixed with /agents.

Authentication

Authentication is handled via an API Key.

Header: x-api-key: <your_api_key>

Quick Start: Build an Agent in 60 Seconds

The fastest way to get started is by using the Quick Create endpoint. This allows you to go from a high-level goal to a fully functional agent in a single step.

Step 1: Create your Agent

Send your goal to the /quick-create endpoint.

  • URL: https://api.muapi.ai/agents/quick-create
  • Method: POST

Request Body:

{
  "prompt": "I want an agent that specializes in creating minimalist streetware brand assets and social media content."
}

Response (200 OK):

{
  "id": "agent_abc123",
  "name": "Streetware Guru",
  "system_prompt": "You are an expert brand designer...",
  "skills": [...]
}

Step 2: Start Chatting

Use the id from the response to start a conversation. To maintain memory across multiple messages, you must provide a consistent conversation_id (any valid UUID).

  • URL: https://api.muapi.ai/agents/{agent_id}/chat
  • Method: POST

Request Body:

{
  "message": "Hey! Let's start by designing a simple logo for a brand called 'Vapor'.",
  "conversation_id": "my-session-123"
}

[!IMPORTANT] If you omit conversation_id, the agent will treat every message as a brand-new interaction and will not remember previous decisions.

Detailed API Reference

The following endpoints provide granular control over the agent lifecycle.

1. Suggest Agent Configuration (Architect)

Generates a recommended agent configuration (persona + skills) based on a high-level goal.

  • URL: https://api.muapi.ai/agents/suggest
  • Method: POST
  • Description: Suggests an agent name, description, system prompt, and skills based on a user prompt.

Request Body:

{
  "prompt": "I want an agent that can help me write python code and debug errors."
}

Response (200 OK):

{
  "name": "Python Wizard",
  "description": "An expert Python developer focused on writing clean, efficient code.",
  "system_prompt": "You are an expert Python developer...",
  "recommended_skill_ids": ["python_exec", "file_io"]
}

2. List Skills

List all available skills that can be assigned to an agent.

  • URL: https://api.muapi.ai/agents/skills
  • Method: GET
  • Description: Returns a list of atomic capabilities (skills).

Response (200 OK):

[
  {
    "id": "web_search",
    "aitask_id": 101,
    "name": "Web Search",
    "description": "Search the internet for information."
  },
  {
    "id": "code_exec",
    "aitask_id": 102,
    "name": "Code Execution",
    "description": "Execute python code."
  }
]

3. Create Agent

Create a new specialized agent.

  • URL: https://api.muapi.ai/agents
  • Method: POST
  • Description: Creates a new agent with specific skills and prompt.

Request Body:

{
  "name": "Research Assistant",
  "description": "Helps gather information.",
  "system_prompt": "You are a helpful research assistant.",
  "skill_ids": ["web_search", "summarization"]
}

Fields:

  • name (string, required): Name of the agent.
  • description (string, optional): Short description.
  • system_prompt (string, required): The core instruction for the agent.
  • skill_ids (array of strings): List of skill IDs to attach.

Response (200 OK):

{
  "id": "agent_12345",
  "name": "Research Assistant",
  "description": "Helps gather information.",
  "system_prompt": "You are a helpful research assistant.",
  "icon_url": null,
  "daily_credit_limit": 100.0,
  "created_at": "2024-01-01T12:00:00Z",
  "skills": [
    {
        "id": "web_search",
        "name": "Web Search",
        ...
    }
  ]
}

4. List User Agents

Get all agents created by the authenticated user.

  • URL: https://api.muapi.ai/agents/user/agents
  • Method: GET

Response (200 OK):

[
  {
    "id": "agent_12345",
    "name": "Research Assistant",
    ...
  },
  {
    "id": "agent_67890",
    "name": "Coding Bot",
    ...
  }
]

5. Get Agent Details

Get details of a specific agent by ID.

  • URL: https://api.muapi.ai/agents/{agent_id}
  • Method: GET

Response (200 OK): Returns the AgentResponse object (same as Create Agent response).

Response (404 Not Found):

{
  "detail": "Agent not found"
}

6. Update Agent

Edit an existing agent. Only the owner can update it.

  • URL: https://api.muapi.ai/agents/{agent_id}
  • Method: PUT

Request Body:

{
  "name": "Advanced Research Assistant",
  "description": "Updated description.",
  "system_prompt": "You are an advanced researcher...",
  "icon_url": "https://example.com/icon.png",
  "skill_ids": ["web_search", "data_analysis"]
}

Note: All fields are optional. Only provided fields will be updated.

Response (200 OK): Returns the updated AgentResponse object.

7. Delete Agent

Delete an agent. Only the owner can delete it.

  • URL: https://api.muapi.ai/agents/{agent_id}
  • Method: DELETE

Response (200 OK):

{
  "status": "success",
  "message": "Agent deleted"
}

Agentic Workflow Architect Integration

Agents are now integrated with the MuAPI Workflow system, allowing them to participate in complex architectural planning.

1. Planning Phase

When an agent receives a broad objective (e.g., "Build an e-commerce branding pipeline"), it enters a Consultant Planning Phase. It will propose multiple architectural directions and wait for your approval before building the workflow graph.

2. Skill-Based Execution

Agents can use the skill_ids to trigger specific nodes in your workflows, effectively acting as an intelligent bridge between chat-based instructions and graph-based automation.

Public Workflow Recipe Discovery

External agents (Claude, Cursor, custom LLM apps) can discover and fetch the workflow recipes the muapi assistant ships with — no API key required. Recipes are end-to-end natural-language SKILL.md files that chain multiple muapi endpoints into a named pipeline (e.g. photo → 3D action figure, product photo → cinematic 10s ad, long video → vertical short clips).

These are different from the atomic skills returned by /agents/skills above: those are individual capabilities you attach to a created agent; these are full multi-step recipes an agent can load and execute directly.

1. List All Recipes

  • URL: https://api.muapi.ai/api/v1/agent-skills
  • Method: GET
  • Auth: None

Response (200 OK):

{
  "skills": [
    {
      "name": "storyboard",
      "description": "Generate N keyframes for a short story or scene sequence (image only, no video).",
      "triggers": ["storyboard", "keyframes", "scene sequence"],
      "inputs": ["premise", "scenes", "style"],
      "estimated_credits": 0,
      "url": "/api/v1/agent-skills/storyboard"
    }
  ]
}

2. Fetch a Recipe Body

  • URL: https://api.muapi.ai/api/v1/agent-skills/{name}
  • Method: GET
  • Auth: None
  • Description: Returns the full markdown body for the recipe — the agent reads it and makes the underlying muapi tool calls itself.

Response (200 OK):

{
  "name": "storyboard",
  "description": "...",
  "inputs": { "premise": { "type": "text", "required": true, "description": "..." }, "scenes": { "type": "int", "default": 6 } },
  "trigger_keywords": ["storyboard", "keyframes"],
  "estimated_credits": 0,
  "body": "# Storyboard\n\nStep 1: ...\nStep 2: ...\n"
}

Response (404):

{
  "detail": {
    "error": { "code": "SKILL_NOT_FOUND", "message": "Unknown skill: foo" },
    "available": ["3d-logo-animation", "action-figure-generator", "..."]
  }
}