back
loading skill details...
Hand off tasks to human assistants and track their completion
---
name: magic api console
version: 1.2.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"
}'
```
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/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"
```
**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 (default: 50, max: 100)
**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"
}'
# 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
don't have the plugin yet? install it then click "run inline in claude" again.