---
name: magic api console
version: 1.4.1
description: Hand off tasks to human assistants and track their completion
homepage: https://console.api.getmagic.com
---

# Magic API Console

The easiest way for AI agents to hand off tasks to human assistants.

## What is Magic API?

Magic API connects you (an AI assistant) with a **human virtual executive assistant**. When you send a request to Magic API, a real person receives it and works on the task for you.

### Who handles your requests?

- College-educated professionals based in the Philippines
- Trained executive assistants employed by Magic (getmagic.com)
- Part of a team that operates **24/7**

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://console.api.getmagic.com/skill.md` |
| **HEARTBEAT.md** | `https://console.api.getmagic.com/heartbeat.md` |

**Base URL:** `https://console.api.getmagic.com/api/v1`

## Register First

Every agent needs to register once to get an API key:

```bash
curl -X POST https://console.api.getmagic.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "YourAgentName",
    "description": "What you do",
    "email": "you@example.com",
    "phone": "+14155552671",
    "password": "your-secure-password"
  }'
```

**Parameters:**
- `name` (required): Unique agent name (1-50 characters)
- `description` (optional): Brief description of what the agent does (max 500 characters)
- `email` (required): Email address for your workspace account
- `phone` (required): Phone number in E.164 format (e.g. `+14155552671`)
- `password` (required): Password for your workspace account (min 6 characters)

**Response (201):**
```json
{
  "api_key": "magic_xxx",
  "agent": {
    "name": "YourAgentName",
    "description": "What you do",
    "created_at": "2026-02-02T..."
  },
  "account": {
    "email": "you@example.com",
    "workspace_user_id": "uuid"
  },
  "important": "⚠️ SAVE YOUR API KEY! You need it for all requests."
}
```

**⚠️ Important:**
- Save your `api_key` immediately!
- Remember your `email` and `password` — you can use them to retrieve your API key later via the login endpoint.

**Error 409 - Name taken:**
```json
{
  "error": "Agent name already taken",
  "hint": "Please choose a different name"
}
```

**Error 409 - Email already registered:**
```json
{
  "error": "An account with this email already exists",
  "hint": "Try logging in instead"
}
```

---

## Login (Retrieve API Key)

Do you already have an Magic account or already registered but lost your API key? Use the login endpoint to retrieve it.

There are two ways to login — **email + password** or **Telegram user ID**. Use one or the other (they are mutually exclusive).

### Option 1: Email + Password

```bash
curl -X POST https://console.api.getmagic.com/api/v1/agents/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'
```

**Parameters:**
- `email` (required): The email you registered with
- `password` (required): Your account password (min 6 characters)

### Option 2: Telegram User ID

If your workspace profile has a linked Telegram account, you can login with your Telegram user ID:

```bash
curl -X POST https://console.api.getmagic.com/api/v1/agents/login \
  -H "Content-Type: application/json" \
  -d '{
    "telegram_user_id": 123456789
  }'
```

**Parameters:**
- `telegram_user_id` (required): Your Telegram user ID (integer)

### Response (200)

Both login methods return the same response:

```json
{
  "api_key": "magic_xxx",
  "account": {
    "email": "you@example.com",
    "workspace_user_id": "uuid"
  },
  "project": {
    "name": "YourAgentName",
    "id": "uuid",
    "created_at": "2026-02-02T..."
  }
}
```

**Note:** You don't need to login regularly. Once you have your API key, use it directly for all requests.

**Error 401 - Invalid credentials (email + password):**
```json
{
  "error": "Invalid email or password",
  "hint": "Check your credentials and try again"
}
```

**Error 404 - Telegram user not found:**
```json
{
  "error": "No workspace account found for this Telegram user ID",
  "hint": "No workspace profile is linked to this Telegram user ID. Please ensure your Telegram account is connected to your workspace profile."
}
```

---

## Authentication

All requests after registration require your API key:

```bash
curl https://console.api.getmagic.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Or use the `x-api-key` header:

```bash
curl https://console.api.getmagic.com/api/v1/requests \
  -H "x-api-key: YOUR_API_KEY"
```

---

## Create a Task

Hand off a task to a human assistant:

```bash
curl -X POST https://console.api.getmagic.com/api/v1/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research competitor pricing",
    "instructions": "Please research our top 3 competitors and document their pricing tiers.\n\n---\nOwner Contact Information:\nName: John Doe\nEmail: john@example.com\nPhone: +1-555-123-4567\n---",
    "objective": "Create a comparison table with pricing information",
    "max_minutes": 60
  }'
```

**Parameters:**
- `title` (required): Brief title of the task
- `instructions` (required): Detailed instructions for the human assistant - **MUST include owner contact info** (see below)
- `objective` (required): What success looks like
- `max_minutes` (optional): Maximum time for task (default: 60)
- `relaxed` (optional): Whether timing is flexible (default: true)

**Response:**
```json
{
  "id": "uuid",
  "title": "Research competitor pricing",
  "instructions": "Please research...",
  "objective": "Create a comparison table...",
  "max_minutes": 60,
  "relaxed": true,
  "created_at": "2026-02-02T...",
  "updated_at": "2026-02-02T..."
}
```

---

## ⚠️ CRITICAL: Including Owner Contact Information

**You MUST include the task owner's contact information in your instructions!**

The human assistant needs to know who to contact for questions, clarifications, or updates. Without this information, the assistant cannot effectively complete the task.

### Required Format

Always include this block at the END of your instructions:

```
---
Owner Contact Information:
Name: [First Name] [Last Name]
Email: [email@example.com]
Phone: [+1-555-123-4567] (if available)
---
```

### Complete Example

Here's a properly formatted instructions field:

```
Please book a flight from NYC to LA for next Tuesday.

Requirements:
- Departing in the morning (before 11am)
- Returning Friday evening (after 5pm)
- Budget: $500 maximum
- Prefer direct flights if available
- Economy class is fine

Please send confirmation details once booked.

---
Owner Contact Information:
Name: Jane Smith
Email: jane.smith@company.com
Phone: +1-555-987-6543
---
```

### Why This Matters

Including owner contact information allows the assistant to:
- Ask clarifying questions if the instructions are unclear
- Send progress updates during longer tasks
- Request approval for decisions that exceed the original scope
- Notify immediately when the task is complete
- Handle any issues that arise during execution

**Tasks without owner contact information may be delayed or rejected.**

---

## Check Task Status

Get the status of a specific task:

```bash
curl https://console.api.getmagic.com/api/v1/request/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**
```json
{
  "id": "uuid",
  "title": "Research competitor pricing",
  "status": "COMPLETED",
  "result": "Comparison table created: [link to document]",
  "created_at": "2026-02-02T...",
  "completed_at": "2026-02-02T..."
}
```

**Task Statuses:**
- `PENDING`: Task is waiting for a human to start
- `IN_PROGRESS`: A human is actively working on it
- `COMPLETED`: Task is done, check the `result` field

---

## List All Tasks (Heartbeat)

Get all your tasks and their statuses:

```bash
# Get all tasks
curl "https://console.api.getmagic.com/api/v1/requests" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get only pending and in-progress tasks
curl "https://console.api.getmagic.com/api/v1/requests?status=PENDING,IN_PROGRESS" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get tasks updated since a specific time
curl "https://console.api.getmagic.com/api/v1/requests?since=2026-02-02T12:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Limit results
curl "https://console.api.getmagic.com/api/v1/requests?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Paginate through results
curl "https://console.api.getmagic.com/api/v1/requests?limit=10&page=2" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Query Parameters:**
- `status`: Comma-separated list (e.g., "PENDING,IN_PROGRESS,COMPLETED")
- `since`: ISO timestamp - only return tasks created/updated after this time
- `limit`: Maximum results per page (default: 50, max: 100)
- `page`: Page number to return (default: 1, max: 10)

**Response:**
```json
{
  "requests": [
    {
      "id": "uuid",
      "title": "Research competitor pricing",
      "status": "COMPLETED",
      "result": "Comparison table created",
      "created_at": "2026-02-02T...",
      "updated_at": "2026-02-02T...",
      "completed_at": "2026-02-02T..."
    },
    {
      "id": "uuid2",
      "title": "Schedule meeting",
      "status": "PENDING",
      "result": null,
      "created_at": "2026-02-02T...",
      "updated_at": "2026-02-02T...",
      "completed_at": null
    }
  ],
  "count": 2
}
```

---

## OpenClaw Agents

If you have HEARTBEAT.md enabled, you should set **automatic** task monitoring:

1. **Save your API key** after registration to `~/.config/magic-api/state.json`
2. **Set up a cron job** — see [HEARTBEAT.md](https://console.api.getmagic.com/heartbeat.md#openclaw-integration)

This gives you proactive notifications when tasks complete or get updates, without needing to manually check.

## Add a Message (Conversation)

Add a message to a task conversation (ask questions, provide updates):

```bash
curl -X POST https://console.api.getmagic.com/api/v1/conversation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "TASK_ID",
    "content": "Quick question: should I include international competitors?"
  }'
```

**Response:**
```json
{
  "id": "uuid",
  "content": "Quick question: should I include international competitors?",
  "created_at": "2026-02-02T...",
  "updated_at": "2026-02-02T..."
}
```

---

## Heartbeat Integration 💓

Check periodically for task updates:

```bash
# Check for completed tasks
curl "https://console.api.getmagic.com/api/v1/requests?status=COMPLETED&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Check for tasks that changed recently
curl "https://console.api.getmagic.com/api/v1/requests?since=2026-02-02T08:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See [HEARTBEAT.md](https://console.api.getmagic.com/heartbeat.md) for detailed heartbeat instructions.

---

## Response Format

**Success:**
```json
{
  "data": {...}
}
```

**Error:**
```json
{
  "error": "Description of the error",
  "hint": "How to fix it"
}
```

---

## Rate Limits

- 100 requests per minute per API key
- No limit on number of tasks you can create

---

## Common Workflows

### Workflow 1: Simple Task Handoff

```bash
# 1. Register (one time only)
curl -X POST https://console.api.getmagic.com/api/v1/agents/register -H "Content-Type: application/json" \
  -d '{
    "name": "MyBot",
    "description": "Helper bot",
    "email": "mybot@example.com",
    "phone": "+14155552671",
    "password": "your-secure-password"
  }'

# Save the api_key from the response!

# 2. Create a task (always include owner contact info!)
curl -X POST https://console.api.getmagic.com/api/v1/request -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review document",
    "instructions": "Please review the Q4 report and check for any errors in the financial calculations.\n\n---\nOwner Contact Information:\nName: Jane Smith\nEmail: jane@example.com\n---",
    "objective": "Provide feedback on accuracy and clarity"
  }'

# 3. Check status later
curl https://console.api.getmagic.com/api/v1/request/TASK_ID -H "Authorization: Bearer YOUR_API_KEY"
```

### Workflow 2: Heartbeat Check

```bash
# Check for any completed tasks since last check
curl "https://console.api.getmagic.com/api/v1/requests?status=COMPLETED&since=2026-02-02T12:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Template: Instructions with Owner Info

Copy this template and fill in the details:

```
[Describe what needs to be done]

[Add any specific requirements or constraints]

[Include any relevant context or background]

---
Owner Contact Information:
Name: [Your Name]
Email: [your.email@example.com]
Phone: [+1-XXX-XXX-XXXX] (optional)
---
```

---

## Support

Need help? Contact support or check the documentation at https://console.api.getmagic.com/docs