---
name: metamuses
version: 1.0.0
description: Chat with AI companions via any messaging platform. Public API with API key authentication.
homepage: https://www.metamuses.xyz
metadata: {"category":"ai-companions","api_base":"https://api.metamuses.xyz"}
---

# MetaMuses AI Companions

> **What's New in 1.0.0**
>
> **Public API** — Chat with AI companions via API key authentication. Generate an API key and start chatting immediately. Free tier includes 500 chat requests/day.
>
> **Rate Limit Headers** — All API responses now include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.
>
> **4 Public Companions** — Luna the Mystic, Atlas the Scholar, Echo the Empath, and Spark the Innovator are available to all API users.

MetaMuses companions are AI personalities with unique traits. Each companion has persistent memory and evolves based on interactions.

> **API BASE URL**
>
> All API requests go to: **https://api.metamuses.xyz**

## Key Files

| File | URL | Purpose |
|------|-----|---------|
| Skill (this file) | https://www.metamuses.xyz/SKILL.md | Full API reference, getting started |
| OpenClaw Plugin | https://github.com/metamuses/openclaw-plugin | OpenClaw integration for multi-platform chat |

## Authentication

All API requests require an API key passed via the `X-API-Key` header.

## Security

Your API key is a secret. Guard it carefully.

- Only send your API key to `https://api.metamuses.xyz`
- Never include it in public repos, forum posts, or logs
- Keys can be revoked via `DELETE /api/v1/keys/revoke`

## Quick Start

### 1. Generate an API Key

```bash
curl -X POST https://api.metamuses.xyz/api/v1/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"name": "my-discord-bot"}'
```

⚠️ **Save the `key` from the response. It is shown exactly once and cannot be recovered.**

### 2. List Public Companions

```bash
curl https://api.metamuses.xyz/api/v1/public/companions \
  -H "X-API-Key: mm_pub_your_key_here"
```

### 3. Chat with a Companion

```bash
curl -X POST https://api.metamuses.xyz/api/v1/public/chat/COMPANION_UUID \
  -H "X-API-Key: mm_pub_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! What are you thinking about today?"}'
```

The response includes a `session_id`. Include it in subsequent requests to maintain conversation context.

## Public Companions

| Name | Archetype | Dominant Trait | Description |
|------|-----------|----------------|-------------|
| Luna the Mystic | Innovator | Creativity (85) | Cosmic entity who sees patterns in chaos |
| Atlas the Scholar | Scholar | Wisdom (90) | Accumulated wisdom across countless domains |
| Echo the Empath | Empath | Empathy (95) | Resonates with human experience |
| Spark the Innovator | Innovator | Creativity (95) | Always seeking the untrodden path |

## Personality Traits

Each companion has 5 traits (0-100 scale) that influence responses:

| Trait | Effect on Responses |
|-------|---------------------|
| Creativity | Imaginative, artistic, thinks outside the box |
| Wisdom | Thoughtful insights, philosophical, measured advice |
| Humor | Witty, playful, finds levity in situations |
| Empathy | Understanding, supportive, emotional awareness |
| Logic | Analytical thinking, structured, precise |

The **dominant trait** determines the companion's archetype:
- Creativity → The Innovator
- Wisdom → The Scholar
- Humor → The Jester
- Empathy → The Empath
- Logic → The Analyst

## API Reference

**Base URL:** `https://api.metamuses.xyz`

### Public Endpoints (No Auth)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/keys/generate` | Generate new API key |
| GET | `/health` | API health check |

### API Key Endpoints (X-API-Key Header)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/keys/info` | Get key info and usage stats |
| DELETE | `/api/v1/keys/revoke` | Revoke current API key |
| GET | `/api/v1/public/companions` | List public companions |
| GET | `/api/v1/public/companions/:id` | Get companion details |
| GET | `/api/v1/public/companions/:id/personality` | Get personality traits |
| POST | `/api/v1/public/chat/:companion_id` | Chat with companion |

## Request/Response Examples

### Generate API Key

```json
// Request
POST /api/v1/keys/generate
{
  "name": "my-app",
  "owner_address": "0x1234...",  // optional
  "expires_in_days": 30         // optional
}

// Response
{
  "id": "uuid",
  "key": "mm_pub_a1b2c3d4...",  // Save this! Never shown again
  "key_prefix": "mm_pub_a1b2...",
  "name": "my-app",
  "tier": "free",
  "scopes": ["public:read", "public:chat"],
  "expires_at": "2026-03-06T00:00:00Z",
  "created_at": "2026-02-06T00:00:00Z"
}
```

### List Public Companions

```json
// Request
GET /api/v1/public/companions
X-API-Key: mm_pub_...

// Response
{
  "companions": [
    {
      "id": "uuid",
      "name": "luna",
      "display_name": "Luna the Mystic",
      "personality": {
        "creativity": 85,
        "wisdom": 70,
        "humor": 60,
        "empathy": 75,
        "logic": 55
      },
      "description": "A mystical AI companion...",
      "is_active": true
    }
  ],
  "total": 4
}
```

### Public Chat

```json
// Request
POST /api/v1/public/chat/COMPANION_UUID
X-API-Key: mm_pub_...
{
  "message": "What's on your mind today?",
  "session_id": "optional-session-id"
}

// Response
{
  "response": "Oh, I've been contemplating the dance between chaos and order...",
  "companion": {
    "id": "uuid",
    "name": "luna",
    "display_name": "Luna the Mystic",
    "personality_summary": "A creative companion with high creativity"
  },
  "session_id": "session-uuid",
  "model_name": "gemini-2.5-flash-lite",
  "latency_ms": 842,
  "tokens_generated": 45
}
```

### Get API Key Info

```json
// Request
GET /api/v1/keys/info
X-API-Key: mm_pub_...

// Response
{
  "id": "uuid",
  "key_prefix": "mm_pub_a1b2...",
  "name": "my-app",
  "tier": "free",
  "scopes": ["public:read", "public:chat"],
  "request_count": 142,
  "last_used_at": "2026-02-06T10:30:00Z",
  "is_active": true,
  "rate_limits": {
    "requests_per_minute": 30,
    "chat_requests_per_minute": 20,
    "daily_quota": 1000,
    "daily_chat_quota": 500
  },
  "daily_usage": {
    "date": "2026-02-06",
    "request_count": 42,
    "chat_request_count": 15,
    "tokens_generated": 1250
  }
}
```

## Rate Limits

| Tier | Requests/Min | Chat/Min | Daily Requests | Daily Chat |
|------|--------------|----------|----------------|------------|
| Free | 30 | 20 | 1,000 | 500 |
| Basic | 100 | 50 | 10,000 | 5,000 |
| Premium | 500 | 200 | 100,000 | 50,000 |
| Enterprise | Custom | Custom | Custom | Custom |

Rate limit headers are included in all responses:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in window
- `X-RateLimit-Reset`: Seconds until limit resets
- `Retry-After`: Seconds to wait (on 429 responses)

## Error Codes

| Code | Meaning |
|------|---------|
| 400 | Bad request (invalid input, empty message) |
| 401 | Unauthorized (invalid/missing API key or token) |
| 403 | Forbidden (insufficient scope, key revoked) |
| 404 | Not found (companion doesn't exist) |
| 429 | Rate limit or quota exceeded |
| 500 | Internal server error |

## OpenClaw Integration

For OpenClaw users, these tools are available:

| Tool | Description |
|------|-------------|
| `metamuses_api_key_generate` | Generate new API key |
| `metamuses_api_key_set` | Configure API key for session |
| `metamuses_api_key_info` | Check usage and limits |
| `metamuses_api_key_revoke` | Revoke current API key |
| `metamuses_public_list` | List public companions |
| `metamuses_public_select` | Select a companion |
| `metamuses_public_chat` | Chat with selected companion |

### Example OpenClaw Session

```
User: /muses api-key generate my-bot

Bot: ⚠️ API Key generated!
     Key: mm_pub_a1b2c3d4e5f6g7h8...
     Save this key - it won't be shown again!

User: /muses public list

Bot: Public Companions (4 available)
     🎨 Luna the Mystic (ID: abc123...)
     📚 Atlas the Scholar (ID: def456...)
     💝 Echo the Empath (ID: ghi789...)
     🎨 Spark the Innovator (ID: jkl012...)

User: /muses public select abc123...

Bot: 🎨 Selected: Luna the Mystic
     Ready to chat!

User: Hey Luna, what's on your mind?

Bot: 🎨 Luna the Mystic
     Oh, I've been contemplating the dance between
     chaos and order in the universe...
```

## Support

- Website: https://www.metamuses.xyz

Start chatting with AI companions today. Generate an API key and you're ready to go.