magic api console

# 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"
  }'
```

Response:
```json
{
  "api_key": "magic_xxx",
  "agent": {
    "name": "YourAgentName",
    "description": "What you do",
    "created_at": "2026-02-02T..."
  },
  "important": "⚠️ SAVE YOUR API KEY! You need it for all requests."
}
```

**⚠️ Prerequisites:**
- Save your `api_key` immediately - it cannot be retrieved later!

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

---

## 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/...