# BAMF Developer Platform

BAMF gives creators and teams a programmable way to draft, edit, schedule, analyze, research, and manage LinkedIn content. The public developer surface has two primary entry points:

- REST API: `https://api.bamf.ai/v1`
- Product MCP: `https://mcp.bamf.ai`
- OpenAPI schema: `https://bamf.ai/openapi.json`

All API and MCP calls resolve to a user, creator space, role, scopes, and request id. A Creator Space is the public API tenant boundary. The database table may still be named `authors`, but public contracts use `creator_id` and Creator Space language.

## Authentication

Use bearer authentication:

```http
Authorization: Bearer bamf_live_...
```

There are two key types:

- User keys can access every creator space the issuing user can access, limited by scopes.
- Creator keys are pinned to one creator space. If a request passes a different `creator_id`, BAMF rejects it.

Creator-scoped keys can create drafts, edit posts, delete normal content, schedule posts, unschedule posts, add knowledge, run research, and read analytics. Creator-scoped keys cannot publish-now to LinkedIn, manage billing, transfer creator spaces, or access other creator spaces.

Send an `Idempotency-Key` header on every mutating request:

```http
Idempotency-Key: 3e9b5e4f-5ff2-41b1-94ef-0e23fb2f7d1b
```

Use idempotency keys for creating or editing posts, scheduling, unscheduling, pausing, resuming, publishing posts, creating generation jobs, creating or deleting knowledge/media/ideas/agent sessions, and creating webhook endpoints.

## Scopes

- `posts:read`: read drafts, scheduled content, previews, first comments, and media attachments.
- `posts:write`: create and edit draft content.
- `posts:schedule`: schedule, unschedule, pause, and resume posts.
- `posts:publish`: publish immediately. This is intentionally narrower than scheduling.
- `analytics:read`: read official LinkedIn metrics from the authoritative analytics pipeline.
- `knowledge:write`: save creator memory, research, source notes, and interview transcripts.
- `ai:generate`: run post, edit, research, brand-kit, and knowledge-processing jobs.
- `images:generate`: run visual jobs, including images, quote cards, and carousels.

## Common Error Shape

```json
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This key cannot publish now.",
    "request_id": "req_..."
  }
}
```

- `401`: missing, revoked, or invalid key.
- `403`: valid key, but scope, role, or creator-space boundary blocks the action.
- `409`: idempotency key was reused with a different method, path, or body.
- `429`: rate limit exceeded.

## Core REST Endpoints

### Creator Spaces

```http
GET /v1/creator-spaces
```

Lists creator spaces visible to the API key. Creator-scoped keys return their pinned creator space.

### Posts

```http
GET /v1/posts?creator_id={creator_id}&status=scheduled&include=media,first_comment,preview
POST /v1/posts
GET /v1/posts/{post_id}
PATCH /v1/posts/{post_id}
DELETE /v1/posts/{post_id}
GET /v1/posts/{post_id}/preview
POST /v1/posts/{post_id}/schedule
POST /v1/posts/{post_id}/unschedule
POST /v1/posts/{post_id}/pause
POST /v1/posts/{post_id}/resume
POST /v1/posts/{post_id}/publish
```

Post workflows are draft-first. Agents should preview scheduled posts before creating new content, then create or update drafts only after exact content approval.

Create a draft:

```bash
curl "$BAMF_API_BASE/posts" \
  -X POST \
  -H "Authorization: Bearer $BAMF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-001" \
  -d '{
    "creator_id": "creator_123",
    "content": "Shipping update: we made the app faster today.",
    "post_type": "text",
    "first_comment": "Optional first comment."
  }'
```

Schedule a post:

```bash
curl "$BAMF_API_BASE/posts/post_123/schedule" \
  -X POST \
  -H "Authorization: Bearer $BAMF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: schedule-001" \
  -d '{ "scheduled_for": "2026-06-01T16:00:00Z" }'
```

### Ideas

```http
GET /v1/ideas?creator_id={creator_id}&status=new&search=founder
POST /v1/ideas
PATCH /v1/ideas/{idea_id}
DELETE /v1/ideas/{idea_id}
```

Use ideas for approved backlog items from research, interviews, Slack or Telegram intake, analytics review, customer calls, or a human prompt.

### Knowledge

```http
GET /v1/knowledge?creator_id={creator_id}&search=pricing
POST /v1/knowledge
PATCH /v1/knowledge/{doc_id}
DELETE /v1/knowledge/{doc_id}
POST /v1/knowledge/process
```

Knowledge documents back creator voice, context, research notes, and memory. Knowledge processing queues a job that extracts summaries, durable facts, voice signals, content ideas, and interview-specific insights.

### Media

```http
GET /v1/media?creator_id={creator_id}
POST /v1/media
POST /v1/generate/images
POST /v1/generate/carousels
POST /v1/generate/carousel-pdfs
```

BAMF supports quote cards, creator portrait images, infographics, external media registration, video thumbnails, and carousel PDFs. LinkedIn carousel/document posts require a PDF, not loose image files.

### Analytics

```http
GET /v1/analytics/summary?creator_id={creator_id}
GET /v1/analytics/posts?creator_id={creator_id}
POST /v1/analytics/sync
```

Late API is the authoritative source for post analytics metrics: impressions, reactions, comments, reshares, and members reached. Apify is the authoritative discovery source for connected creators. Scraped impressions are not authoritative and may be marked estimated until Late overwrites with official metrics.

### Jobs

```http
POST /v1/generate/posts
POST /v1/generate/post-edits
POST /v1/research
POST /v1/knowledge/process
POST /v1/generate/images
POST /v1/generate/carousels
POST /v1/generate/carousel-pdfs
POST /v1/jobs
GET /v1/jobs/{job_id}
DELETE /v1/jobs/{job_id}
```

Long-running operations return a job immediately. Poll until `succeeded`, `failed`, or `cancelled`. Typed endpoints are preferred for common workflows because they provide clearer validation and tool schemas.

Generate a reviewable post candidate:

```bash
curl "$BAMF_API_BASE/generate/posts" \
  -X POST \
  -H "Authorization: Bearer $BAMF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-gen-001" \
  -d '{
    "creator_id": "creator_123",
    "brief": "Founder POV post about the operational reality under foundation models.",
    "post_type": "text",
    "include_first_comment": true
  }'
```

### Webhooks

```http
POST /v1/webhooks
```

Webhook payloads are signed with a per-endpoint secret:

```http
bamf-signature: v1=<hmac_sha256>
bamf-timestamp: 1779801600
```

Common events include `post.scheduled`, `post.published`, `job.succeeded`, `job.failed`, `analytics.updated`, and `knowledge.processed`.

## Product MCP

Product MCP URL:

```text
https://mcp.bamf.ai
```

MCP uses the same API keys, scopes, creator-space boundaries, and audit logs as REST. Transport is Streamable HTTP.

Example MCP configuration:

```json
{
  "mcpServers": {
    "bamf": {
      "url": "https://mcp.bamf.ai",
      "headers": {
        "Authorization": "Bearer $BAMF_API_KEY"
      }
    }
  }
}
```

Important tools:

- `bamf.list_creator_spaces`
- `bamf.list_scheduled_posts`
- `bamf.preview_post`
- `bamf.create_post_draft`
- `bamf.edit_post`
- `bamf.delete_post`
- `bamf.schedule_post`
- `bamf.unschedule_post`
- `bamf.create_job`
- `bamf.search_knowledge`
- `bamf.add_memory`

Recommended tool order:

1. `bamf.list_creator_spaces`
2. `bamf.list_scheduled_posts`
3. `bamf.search_knowledge`
4. Propose exact content to the user
5. `bamf.create_post_draft`
6. `bamf.schedule_post` only after explicit date/time approval

## BAMF Stack

BAMF Stack is the local agent kit for Codex, Claude Code, and similar coding agents. It installs BAMF skills, Claude Code slash commands, a local helper CLI, reusable prompts, and routing snippets so an agent can verify auth, inspect creator context, draft safely, plan media, and use MCP/REST without relearning the workflow every session.

```bash
curl -fsSL https://bamf.ai/bamfstack/install.sh | bash
```

Installed workflows:

```text
/bamf-setup     Configure env + MCP
/bamf-smoke     Read-only REST/MCP proof
/bamf-context   Gather creator posts, ideas, knowledge, media, analytics
/bamf-ideas     Capture, refine, and manage creator ideas
/bamf-research  Research topics and save approved knowledge handoffs
/bamf-interview Prepare interviews, import transcripts, extract insights
/bamf-draft     Propose and create approved drafts
/bamf-edit      Safely rewrite posts, first comments, media, and post types
/bamf-schedule  Schedule approved posts
/bamf-media     Plan images, carousels, infographics
/bamf-notion    Save review plans to Notion or local markdown
```

## Safe Agent Prompt

```text
Use BAMF. My BAMF API key is already available as BAMF_API_KEY. Do not print it.

REST base URL: https://api.bamf.ai/v1
MCP URL: https://mcp.bamf.ai

First:
1. Verify auth with GET /me or bamf.list_creator_spaces.
2. List creator spaces and ask me which creator_id to use if there is more than one.
3. Preview scheduled posts with media, first comments, and carousel slides.
4. Read relevant ideas, knowledge, analytics, and media before drafting.

Then:
1. Propose 3 post concepts and any image/carousel plan.
2. Wait for my approval of the exact content.
3. Create a draft only after approval.
4. Schedule only after I give an exact date, time, timezone, and approval.

Always use an Idempotency-Key header for POST, PATCH, and DELETE. Never publish-now unless I explicitly ask for it.
```