knky · API access · dev brief

knky API access — developer brief

Programmatic creator-side access via personal access tokens — schedule posts/stories/clips, mass-DM, shop, vault, and read the scheduled feed. Wraps knky's existing internal endpoints with token auth + rate limits. Scoped per creator, moderation-enforced.

1. Goal

Give partner tools (creator-management agencies, scheduling apps, mass-DM automators) programmatic access to act on a creator's behalf — schedule posts, stories and clips, send mass-DMs, manage shop products, manage the vault, and read what's scheduled. A partner's software authenticates as the creator via a token the creator generates, and drives knky through the API instead of the web UI.

This is not a new API build — knky's own frontend already calls authenticated endpoints for all of this. The work is an access-control layer: token auth + scoping + rate limits in front of the endpoints that exist.

2. Approach — wrap existing internal endpoints

Don't redesign the posting/stories/mass-DM/shop/vault logic. Add a thin layer in front of the existing route handlers:

Incoming API request  →
  1. parse Authorization: Bearer knky_pat_…
  2. look up api_tokens by SHA-256 hash; reject if revoked/expired
  3. assert the token's scope covers this resource family
  4. attach the token's user_id to the request as the acting creator
  5. apply rate-limit middleware (per token)
  6. forward to the EXISTING internal route handler unchanged

Goal: zero new business logic. Posting via API hits the same code (and the same moderation pipeline) as posting via the web app.

3. Schema — minimal additions

api_tokens
  _id, user_id,                       // the creator the token acts as
  name,                               // human label, e.g. "AgencyTool prod"
  prefix,                             // first 8 chars, shown in UI
  hash,                               // SHA-256 of the full token (never store raw)
  scopes[],                           // ['posts:write','vault:read', …]
  rate_limit_tier,                    // 'standard' | 'pro'
  created_at, last_used_at, revoked_at, expires_at?

api_token_audit  (TTL'd / capped collection)
  _id, token_id, ts, ip, endpoint, status_code

Token format: knky_pat_<32-char-base32>. Shown to the creator ONCE on generation; store only the hash. A token belongs to ONE creator and can only act on that creator's resources — there is no agency-level or super-token in v1.

Scopes

posts:read   posts:write
stories:read stories:write
clips:read   clips:write
mass_dm:read mass_dm:write
shop:read    shop:write
vault:read   vault:write
scheduled:read   (read-only derived view)

4. Endpoint surface

Public routes under https://api.knky.co/v1, each wrapping the matching internal handler. JSON in/out, Bearer token + scope required.

4.1 Posts

POST   /v1/posts        # create / schedule
  body: { kind, media_ids[], caption, visibility, scheduled_at?, channels?[], explore? }
GET    /v1/posts/:id
GET    /v1/posts        # ?status=scheduled|live|draft
PATCH  /v1/posts/:id    # only while scheduled, not after publish
DELETE /v1/posts/:id

4.2 Stories

POST   /v1/stories      # { media_ids[], scheduled_at?, ttl_hours? (default 24) }
GET    /v1/stories/:id
GET    /v1/stories
DELETE /v1/stories/:id

4.3 Clips

POST   /v1/clips        # video only
GET    /v1/clips/:id
GET    /v1/clips
DELETE /v1/clips/:id

4.4 Mass DM

POST   /v1/mass_dm      # create job
  body: { audience: { tier?, subscribed_since?, exclude_user_ids? },
          body, media_ids?[], scheduled_at?, price_cents? (PPV) }
GET    /v1/mass_dm/:id  # status + per-recipient counts
GET    /v1/mass_dm
POST   /v1/mass_dm/:id/cancel

Anti-spam enforced on POST: max 1 mass-DM per creator per 6h (standard tier), max recipients = the creator's active fan count, body must pass the same moderation classifier as in-app messages, paying-fan filters require a KYC-verified creator.

4.5 Shop products

POST   /v1/shop/products
  body: { title, price_cents, currency, kind, cover_media_id, description?,
          inventory?, scheduled_at?, sale_start_at? }
GET    /v1/shop/products/:id
GET    /v1/shop/products
PATCH  /v1/shop/products/:id
DELETE /v1/shop/products/:id

4.6 Vault

POST   /v1/vault/upload  # multipart; returns media_id + status
  → status='processing' until moderation + transcode complete (poll or webhook)
GET    /v1/vault         # ?folder= &type= &status=
GET    /v1/vault/:id
PATCH  /v1/vault/:id     # rename / move folder
DELETE /v1/vault/:id

4.7 Scheduled (unified read)

GET /v1/scheduled
  ?kind=post|story|clip|mass_dm|shop|all (default all)
  &from=YYYY-MM-DD&to=YYYY-MM-DD&page=1&per_page=50
  → { items: [{ kind, id, scheduled_at, summary, status }], next_page? }

Answers "show me everything this creator has planned for next week."

4.8 Webhooks (optional v1)

Each token can register a webhook URL. Events: post.published, story.published, media.processed, mass_dm.completed, shop_product.sold. v1 uses a per-token shared secret in the header; HMAC signing can come later.

5. Rate limits

Tier	Read	Write	Mass DM	Vault upload
standard (default)	60 req/min	30 req/min	1 per 6h	10/hour
pro (manual grant)	300 req/min	150 req/min	1 per 2h	60/hour

Headers on every response: X-RateLimit-Limit / -Remaining / -Reset. 429 + Retry-After on overage. Pro tier requires manual review (partnership status + fraud check).

6. Guardrails — non-negotiable

Hive moderation runs on every media uploaded via the API — same pipeline as web upload. The token can't bypass the queue.
KYC + 2257 — the acting creator's existing requirements still apply; the API can't post if they're not met.
Mass-DM rate limit + body moderation — see §4.4.
Self-engagement detection — token activity correlating with the token owner (same IP/fingerprint) on engagement actions → flag + suspend.
Per-token audit log visible to the creator + admin: every call, status, IP. The creator can revoke any token instantly → all its calls 401 immediately.

7. Creator UI — token management

Add an "API access" section to the existing creator settings page:

"Generate a new token" → name + scope picker → token shown ONCE.
List of active tokens: name, prefix, scopes, last used, "Revoke".
Connected-apps view (optional, if partner tools self-identify).
Audit log: last ~1000 events.

Same UX pattern as the affiliate panel (§6 of the knky affiliates brief) — reuse the components.

8. Partner onboarding

Partner signs the API Partner T&Cs (moderation liability, rate-limit enforcement, token revocation rights, no PII export beyond the creator's own data).
Each of their creators generates a scoped token in knky settings.
Partner stores tokens encrypted at rest, calls the API per token.
A sandbox creator account is provided for integration testing.

Per-creator tokens mean a creator leaving the agency revokes their token → the agency loses access to that one creator; the rest are unaffected. Clean blast radius.

9. Estimate — ~5 dev-days

Piece	Days
api_tokens schema + auth middleware + scope check	~1.5
Public routes wrapping internal handlers (~6 families)	~1.5
Rate-limit middleware (Redis token bucket)	~0.5
Creator UI — tokens panel + audit log	~1
Docs + Postman collection	~0.5
Total v1	~5 dev-days

+ ~1 day polish + sandbox setup. Small because we're wrapping existing endpoints, not building from scratch.

10. What we need to confirm

The exact internal route shapes for posting / stories / mass-DM / shop / vault / scheduled, so the wrap is "auth + forward" rather than re-implementation.
Where the creator settings page lives, to slot the §7 token panel.
Whether to ship the optional webhooks in v1 or defer.
Pricing/T&Cs for API partners (business decision).