# wavpost — LLM Reference

A unified social media publishing API. One API key, one call to publish across LinkedIn, Twitter, Telegram, and YouTube.

Base URL: http://localhost:3000

## Authentication

All endpoints require a Bearer token in the Authorization header.
Two token types accepted:
- API key: starts with `sk_live_` (recommended for agents)
- Firebase ID token: JWT from Firebase Auth

```
Authorization: Bearer sk_live_your_key_here
```

## Core Workflow for AI Agents

1. Check which platforms are connected: GET /api/connect/status
2. Publish a post: POST /api/v1/posts
3. Verify it was logged: GET /api/logs

---

## Endpoints

### POST /api/v1/posts — Publish a post

Required fields: text (string), platforms (array)
Optional fields: mediaUrls (array of public image URLs, up to 9), scheduledFor (ISO datetime), profile (profile slug)

Supported platform values: "linkedin", "twitter", "telegram", "youtube"

Request:
```json
{
  "text": "Hello world!",
  "platforms": ["linkedin", "twitter"],
  "mediaUrls": ["https://example.com/image.jpg"],
  "scheduledFor": "2025-06-01T09:00:00Z"
}
```

Response (201):
```json
{
  "id": "uuid",
  "text": "Hello world!",
  "platforms": ["linkedin", "twitter"],
  "status": "published",
  "createdAt": "2025-03-19T07:00:00Z",
  "platformResults": {
    "linkedin": { "ok": true, "platformPostId": "urn:li:share:123" },
    "twitter": { "ok": false, "error": "Twitter not connected." }
  }
}
```

Notes:
- If a platform is not connected, that platform result will have ok=false with an error, but the post still succeeds for other platforms.
- mediaUrls must be publicly accessible (no auth, no bot blocking). LinkedIn supports up to 9 images.
- Text limit: 3000 characters for LinkedIn.

---

### GET /api/v1/posts — List posts

No query parameters required.

Response (200):
```json
{
  "posts": [{ "id": "uuid", "text": "...", "platforms": ["linkedin"], "status": "published", "createdAt": "..." }]
}
```

---

### GET /api/connect/status — Check platform connections

Optional query param: profileId (uses default profile if omitted)

Response (200):
```json
{
  "linkedin": { "connected": true, "displayName": "Anshu Raj Singh" },
  "twitter": { "connected": false, "displayName": null },
  "telegram": { "connected": false, "displayName": null },
  "youtube": { "connected": false, "displayName": null }
}
```

---

### GET /api/logs — Activity logs

Query params: limit (default 50, max 200), offset (default 0)

Response (200):
```json
{
  "logs": [
    {
      "id": "uuid",
      "action": "post.published",
      "platform": "linkedin",
      "status": "success",
      "metadata": { "text": "Hello world!", "platformPostId": "urn:li:share:123" },
      "createdAt": "2025-03-19T07:00:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}
```

Log action values: post.published, platform.connected, platform.disconnected, profile.created, profile.deleted

---

### GET /api/profiles — List profiles

Response (200):
```json
{
  "profiles": [
    { "id": "uuid", "name": "Default", "slug": "default", "isDefault": true, "createdAt": "..." }
  ]
}
```

---

### POST /api/profiles — Create a profile

Request:
```json
{ "name": "My Brand" }
```

Response (201):
```json
{ "profile": { "id": "uuid", "name": "My Brand", "slug": "my-brand", "isDefault": false, "createdAt": "..." } }
```

---

### PATCH /api/profiles/{profileId} — Update a profile

Request (all fields optional):
```json
{ "name": "New Name", "isDefault": true }
```

---

### DELETE /api/profiles/{profileId} — Delete a profile

Response (200): `{ "ok": true }`

---

### GET /api/keys — List API keys

Response (200):
```json
{
  "keys": [
    { "id": "uuid", "name": "My key", "keyPreview": "...a3f9", "createdAt": "...", "lastUsedAt": "..." }
  ]
}
```

---

### POST /api/keys — Create an API key

Request:
```json
{ "name": "Agent key" }
```

Response (201):
```json
{
  "key": { "id": "uuid", "name": "Agent key", "keyPreview": "...x9z2" },
  "rawKey": "sk_live_abc123..."
}
```

IMPORTANT: rawKey is shown only once. Store it securely immediately.

---

### DELETE /api/keys/{keyId} — Revoke an API key

Response (200): `{ "ok": true }`

---

### POST /api/connect/{platform}/disconnect — Disconnect a platform

Platform values: linkedin, twitter, telegram, youtube

Request (optional):
```json
{ "profileId": "uuid" }
```

Response (200): `{ "ok": true }`

---

### GET /api/auth/{platform} — Start OAuth (browser redirect)

Not useful for agents directly — this is a browser-based OAuth flow.
Users visit this URL in their browser to connect a social account.
Query param: profileId (optional)

---

## Error Responses

All errors return JSON:
```json
{ "error": "Human-readable error message" }
```

Common HTTP status codes:
- 400 — Bad request (missing or invalid fields)
- 401 — Unauthorized (missing or invalid token)
- 404 — Resource not found
- 201 — Created successfully
- 200 — Success

---

## Platforms Reference

| Platform  | ID        | Post text | Post images | Notes                        |
|-----------|-----------|-----------|-------------|------------------------------|
| LinkedIn  | linkedin  | Yes       | Yes (up to 9)| 3000 char limit             |
| Twitter/X | twitter   | Yes       | Not yet     | OAuth PKCE flow              |
| Telegram  | telegram  | Yes       | Not yet     | Bot token based              |
| YouTube   | youtube   | Yes       | Not yet     | OAuth flow                   |

---

## Machine-readable spec

OpenAPI 3.0 spec available at: /openapi.json