# CreatorMind API — Bot Instructions

You have access to the CreatorMind API. Use it to discover creators, search their content, chat with their AI representation, and download video transcripts.

## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer API_KEY
```

Replace `API_KEY` with your actual key (starts with `cm_`).

Base URL: `BASE_URL` (replace with the actual domain, e.g. `https://creatormind.ai`)

---

## Endpoints

### 1. Discover Creators

List all creators accessible to you. **Call this first** to get creator IDs for other endpoints.

```
GET BASE_URL/api/v1/creators
Authorization: Bearer API_KEY
```

**Response:**
```json
{
  "success": true,
  "creators": [
    {
      "id": "uuid",
      "name": "Creator Name",
      "description": "Channel description",
      "thumbnailUrl": "https://...",
      "youtubeChannelId": "UC...",
      "subscriberCount": 150000,
      "totalVideos": 200,
      "processedVideos": 180,
      "status": "ready"
    }
  ]
}
```

### 2. Search Creator Content

Vector similarity search across creator transcripts. Returns relevant content chunks ranked by similarity.

```
POST BASE_URL/api/v1/search
Authorization: Bearer API_KEY
Content-Type: application/json

{
  "query": "What does the creator say about AI?",
  "creatorId": "CREATOR_ID",       // optional — omit to search all creators
  "videoId": "VIDEO_ID",             // optional — restrict search to one video
  "maxResults": 10                   // optional — 1 to 50, default 10
}
```

**Response:**
```json
{
  "success": true,
  "results": [
    {
      "videoId": "uuid",
      "content": "Transcript chunk text...",
      "similarity": 0.892,
      "videoTitle": "Video Title",
      "youtubeVideoId": "dQw4w9WgXcQ",
      "startTime": 120.5,
      "endTime": 145.2
    }
  ]
}
```

Use `videoId` (internal UUID) with the Transcript endpoint: `GET /api/v1/transcripts/{videoId}`

### 3. Chat (RAG)

Ask a question and get an AI-generated answer grounded in the creator's actual content, with source references.

```
POST BASE_URL/api/v1/chat
Authorization: Bearer API_KEY
Content-Type: application/json

{
  "creatorId": "CREATOR_ID",        // required
  "message": "Summarize their views on AI",
  "conversationId": "CONV_ID",      // optional — include to continue a conversation
  "videoId": "VIDEO_ID"             // optional — answer only from this video
}
```

**Response:**
```json
{
  "success": true,
  "response": "Based on their videos, the creator believes...",
  "sources": [
    {
      "videoId": "uuid",
      "videoTitle": "Video Title",
      "youtubeVideoId": "dQw4w9WgXcQ",
      "timestamp": 120,
      "youtubeUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ&t=120",
      "contentSnippet": "Relevant quote from transcript..."
    }
  ],
  "conversationId": "uuid",
  "messageId": "uuid"
}
```

### 4. Get Transcript

Download the full transcript for a specific video.

```
GET BASE_URL/api/v1/transcripts/VIDEO_ID
Authorization: Bearer API_KEY
```

**Response:**
```json
{
  "success": true,
  "transcript": {
    "videoId": "uuid",
    "videoTitle": "Video Title",
    "youtubeVideoId": "dQw4w9WgXcQ",
    "creatorName": "Creator Name",
    "text": "Full transcript text...",
    "language": "en",
    "duration": 600.0,
    "segments": [
      { "start": 0.0, "end": 5.2, "text": "Hello everyone..." },
      { "start": 5.2, "end": 10.1, "text": "Today we're going to..." }
    ]
  }
}
```

---

## Recommended Workflow

1. **Discover** — `GET /api/v1/creators` to list available creators and their IDs
2. **Search** — `POST /api/v1/search` to find relevant content chunks
3. **Chat** — `POST /api/v1/chat` to ask questions and get sourced answers
4. **Transcript** — `GET /api/v1/transcripts/VIDEO_ID` to get full video transcripts when needed

---

## Error Codes

| Status | Meaning |
|--------|---------|
| 400 | Bad request — validation failed (check `details` field) |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — you don't have access to this creator |
| 404 | Not found — video or transcript doesn't exist |
| 429 | Rate limited — message quota exceeded (check `quota` field) |
| 500 | Internal server error |

All error responses follow this shape:
```json
{
  "success": false,
  "error": "Human-readable error message"
}
```