Jestha/Developer docs

Reference

Scopes

A scope is one named permission your API key holds. Pick the minimum your integration needs. Scopes are set at key creation and can't be changed afterwards — to change scopes, generate a new key and revoke the old one.

Catalog

Post Jes

write:jes

Create and edit the bound account's Jes (text + media). Includes bounces and quote-bounces.

POST /api/posts, PATCH /api/posts/:id (own only), POST /api/posts/:id/bounce

Post JesClips

write:jesclip

Create and edit the bound account's JesClips (short videos). Media upload is included — no separate media scope.

POST /api/jesclips, PATCH /api/jesclips/:id (own only)

Comment

write:comment

Post comments and replies on any Jes the bound account can see, including its own.

POST /api/posts/:id/comments, POST /api/jesclips/:id/comments

Read comments

read:comment

Read the comment thread on a single Jes by ID. There is no scope that lets you list comments across Jes — you must know the Jes id (e.g. from a webhook).

GET /api/posts/:id/comments

Read engagement counts

read:engagement

Read like / comment / bounce / save counts on a single Jes by ID. Useful for analytics dashboards over the bound account's own content.

(counts embedded in single-Jes GETs)

Manage webhooks

webhooks:manage

Add, remove, and test the webhook endpoints attached to this key. Not required for receiving webhook deliveries — only for managing them via API instead of from the web UI.

POST /api/auth/api-keys/:id/webhooks, DELETE /api/auth/api-keys/:id/webhooks/:webhookId

Not available, regardless of scope

Some endpoints are blocked for API key callers no matter which scopes the key holds. These are session-only operations, by design:

  • ✕The home feed, JeHub feeds, JesClip feed, trending, discover — anything that lists content
  • ✕Searching users, Jes, or hashtags
  • ✕Reading other users' profiles beyond the public snippet attached to a single Jes
  • ✕Liking content (writing likes is intentionally not exposed in v1)
  • ✕Account management — email, password, 2FA, account deletion
  • ✕Creating, revoking, or listing API keys
  • ✕Admin operations

Discovery — feeds, search, trending — stays in the Jestha app. We don't expose it to API keys at any level. Apps publish to and react on Jestha; they can't replace it.

Picking the right scopes

Smallest set that gets the job done. Examples:

  • A scheduling tool that posts on a cron: write:jes, write:jesclip if videos are in scope.
  • A moderation dashboard that watches comments: read:comment, read:engagement, plus webhooks:manage if it sets up its own endpoints.
  • A cross-poster that publishes elsewhere first: write:jes, write:comment.

The settings UI shows each scope's description as you check it — see Settings → API access.