# Yap API — Agent Reference

Yap is a social media management tool. You manage content by making HTTP requests to the API.

## Authentication

Include on every request:
  Authorization: Bearer <your-api-key>

## Base URL

https://yap.ninja/api

## Rate Limits

Requests are rate-limited per API key using a sliding window:

- **Reads** (GET/HEAD): 60 requests/minute
- **Writes** (POST/PUT/PATCH/DELETE): 20 requests/minute
- **Publish** (POST /publish/*): 5 requests/minute

When rate-limited, you'll receive a 429 response:
  { "error": "Rate limit exceeded", "limit": 60, "retryAfter": 12 }

Headers included:
  Retry-After: 12
  X-RateLimit-Limit: 60
  X-RateLimit-Remaining: 0

Wait for the Retry-After duration before retrying.

## Endpoints

### Drafts (your main workflow)

POST /drafts
  Create a draft post.
  Body: { content: string, platform?: "X"|"LinkedIn" (default "X"), isThread?: boolean, threadParts?: string[], lanes?: string[], products?: string[], attachments?: string[] }

GET /drafts
  List drafts. Query: ?status=draft|approved|scheduled|posted|rejected&limit=20

GET /drafts/:id
  Get a single draft.

PATCH /drafts/:id
  Update a draft. Body: { content?, status?, threadParts?, attachments?, rejectionNote? }
  Set status to "approved" when ready to publish.

DELETE /drafts/:id
  Delete a draft.

### Publishing

POST /publish/now
  Publish a draft immediately to the connected platform.
  Body: { draftId: string }

### Scheduling

POST /scheduler
  Schedule a draft for a specific time.
  Body: { draftId: string, scheduledAt: string (ISO datetime) }

GET /scheduler
  List scheduled posts.

PATCH /scheduler/:id
  Update a scheduled post. Body: { scheduledAt? }

DELETE /scheduler/:id
  Cancel a scheduled post.

### Content Calendar / Slots

GET /slots
  Get the weekly slot configuration (time blocks and targets per platform).

GET /slots/next-available
  Find the next open posting slot. Query: ?platform=X|LinkedIn

GET /slots/fill
  See which slots are filled vs. empty this week.

POST /slots
  Create a slot config. Body: { dayOfWeek: 0-6, timeBlock: string, platform: string, targetCount: number, startHour: number, endHour: number }

### Ideas

POST /ideas
  Create a content idea. Body: { title: string, notes?: string, lanes?: string[], products?: string[], platform?: string }

GET /ideas
  List ideas. Query: ?status=idea|used&limit=20

PATCH /ideas/:id
  Update an idea. Body: { title?, notes?, status?, lanes?, products? }

DELETE /ideas/:id
  Delete an idea.

### Voice Profiles

GET /voice
  Get voice profiles (writing style guides). Use these to match the user's tone.

POST /voice
  Create a voice profile. Body: { platform: string, name: string, description?: string, examples?: string[] }

PATCH /voice/:id
  Update a voice profile.

### Analytics

GET /analytics
  Get analytics for posted content.

GET /analytics/summary
  Get aggregate analytics summary.

POST /analytics/refresh
  Refresh analytics data from platform APIs.

### Reply Guy (social engagement)

GET /replies/targets
  List accounts being watched for reply opportunities.

POST /replies/targets
  Add an account to watch. Body: { accountHandle: string, keywords?: string[] }

GET /replies/candidates
  List reply candidates (tweets worth replying to). Query: ?status=new|replied|skipped&limit=20

PATCH /replies/candidates/:id
  Update a candidate. Body: { status?, replySuggestions? }

DELETE /replies/candidates/:id
  Delete a candidate. Returns { deleted: true, id }.

### X (Twitter) Account

GET /auth/x/status
  Check if an X account is connected.

### X API Credentials (BYOK — Optional)

Users can bring their own X API credentials to avoid platform usage limits.

GET /settings/x-credentials — Check if custom credentials are set
  Returns: { hasCredentials: boolean, clientId: string | null }

POST /settings/x-credentials — Save custom X API credentials
  Body: { clientId: string, clientSecret: string }

DELETE /settings/x-credentials — Remove custom credentials

### X API Usage & Budget

GET /settings/usage — Get current month's X API usage and spend
  Returns: { reads: number, writes: number, total: number, spentCents: number, budgetCents: number, month: string }

GET /settings/x-limits — Get budget settings
  Returns: { monthlyBudgetCents: number, alertEmail: string | null }

POST /settings/x-limits — Set monthly budget
  Body: { monthlyBudget: number (dollars), alertEmail?: string }
  Budget minimum: $1.00. Default: $20.00/month.
  Reads are blocked when the budget is exceeded.

## Reply Guy Workflow

Reply Guy helps the user engage with other accounts by finding tweets worth replying to and generating on-brand reply suggestions.

### Setup (first time)
1. GET /voice — Learn the user's writing style so replies match their tone
2. POST /replies/targets — Add accounts to watch. Pick accounts in their niche that post frequently and get good engagement.
   Body: { accountHandle: "levelsio", keywords: ["AI", "indie"] }
3. Repeat step 2 for 5-15 target accounts

### Finding & Pushing Candidates
1. For each target account, find their recent tweets (last 24h) that have good engagement
2. Look for tweets with high likes/retweets but relatively few replies (best reply opportunity)
3. For each good tweet, push it as a candidate with reply suggestions:
   POST /replies/candidates
   Body: {
     externalPostId: "tweet_id_from_x",
     authorHandle: "levelsio",
     authorName: "Pieter Levels",
     content: "the tweet text",
     engagement: { likes: 450, retweets: 32, replies: 18, views: 25000 },
     platform: "X",
     tweetedAt: "2026-03-12T10:30:00Z",
     replySuggestions: ["reply option 1", "reply option 2", "reply option 3"]
   }
4. Generate 2-3 reply suggestions per candidate, written in the user's voice
5. The user reviews suggestions in the UI and copies the ones they like

### Maintaining
- Run this daily — look for new tweets from targets, push fresh candidates
- Old candidates (>24h) auto-filter out of the default view
- Check GET /replies/candidates?status=new to see what's pending review
- If duplicate externalPostId, the API upserts (updates the existing record)

### Tips for Good Replies
- Read the user's voice profile carefully — match their tone exactly
- Short replies (1-2 sentences) perform best
- Add genuine value — insight, experience, or a useful question
- Don't be generic. Reference something specific in the tweet.
- Avoid: "Great post!", "This is so true!", "Couldn't agree more!"

## Typical Workflow

1. GET /voice — Learn the user's writing style
2. GET /slots — Understand the posting schedule
3. GET /slots/next-available?platform=X — Find when to post next
4. POST /drafts — Create a draft in their voice
5. Wait for user approval (they set status to "approved" in the UI)
6. POST /scheduler — Schedule it, or POST /publish/now to post immediately