List the user's posts. Returns post objects with id, caption, status, target platforms, scheduled time, and attached media ids, plus a cursor field when more pages exist. Use this to find a post's id before calling get_post, update_post, delete_post, or publish_post, or to review upcoming scheduled content. For per-platform delivery outcomes or metrics, prefer list_post_results or list_analytics instead.

Fetch a single post by id, including its full per-platform publish results (success or error per platform). Use after list_posts to inspect one post in detail, or after publish_post to check how delivery went. Returns an error if the id does not exist or belongs to another account.

Create a new post as a draft or schedule it for automatic publishing. With status='draft' (or is_draft=true) the post is saved with no publish time; with scheduledFor set it is queued and publishes automatically at that time. Returns the created post object including its id. Media must already exist in the library — call import_media or list_media first to get a media id. The user must have connected each target platform (verify with list_social_accounts if unsure). To publish an existing draft immediately, use publish_post rather than creating a new post.

Edit a draft or scheduled post before it publishes. Send only the fields to change — omitted fields keep their current values. Returns the updated post object. Posts that are already publishing, published, or failed cannot be edited. Common uses: reschedule by passing a new scheduledFor, fix a caption, swap attached media, or convert a draft to scheduled by passing status='scheduled' together with scheduledFor.

Permanently delete a post by id. If the post is scheduled, this cancels the pending publish. This does not retract content already delivered to social platforms — it only removes the ViralNote record. Irreversible: confirm with the user before deleting. Use update_post instead if the goal is to fix or reschedule a post.

Publish an existing draft post to all of its target platforms immediately, skipping the schedule queue. Only valid on posts with status='draft' — returns an error for scheduled or already-published posts. Returns the post with delivery kicked off; individual platforms can still succeed or fail independently, so follow up with get_post or list_post_results to confirm the outcome.

List items in the user's media library. Returns each item's id, name, type, and folder, plus a cursor field when more pages exist. Use this to find a media id to attach to a post via create_post or update_post, or to check whether a file was already imported before calling import_media.

Import a file into the media library so it can be attached to posts. Two modes: (1) URL mode — pass url with an HTTPS direct-download link (up to 200MB; Dropbox and Canva share links supported via the matching source); (2) inline mode — pass data with base64-encoded bytes (3MB max before encoding) plus mimeType, with source='direct'. Exactly one of url or data must be provided. Returns the created library item including the id to use in create_post. For files over 3MB, always use URL mode.

Permanently delete a media library item by id. The file cannot be recovered — confirm with the user before deleting. Use list_media to find the item's id and verify it is the right file (check name and type) first.

List the social accounts connected to the user's ViralNote account: platform and account identity for each. Takes no parameters. Use before create_post to confirm the intended target platforms are actually connected — posting to an unconnected platform fails. Note that connecting or disconnecting accounts happens in the ViralNote dashboard UI (OAuth); it cannot be done through this API.

List published posts with their latest per-platform metrics: views, likes, comments, shares, and engagement. Metrics are collected periodically by ViralNote, so values are the most recent snapshot rather than real-time. Use to report on content performance or find top-performing posts; use list_post_results instead when the question is whether delivery succeeded. Paginated via cursor.

Check delivery outcomes: returns recent published or failed posts with each platform's individual result (success, or the error that occurred). Pass postId to inspect one post's delivery; omit it to scan recent posts filtered by status. Use after publish_post to verify delivery, or when the user asks why a post didn't appear on a platform. For engagement metrics rather than delivery status, use list_analytics.

List all webhook subscriptions on the account: each subscription's id, target URL, and subscribed events. Takes no parameters. Use to find a webhookId before delete_webhook, or to check whether an event is already covered before calling create_webhook (avoids duplicate subscriptions).

Subscribe a URL to ViralNote event notifications. ViralNote sends an HTTP POST with a JSON payload to the URL each time a subscribed event fires — for example post.published when a post goes live, or post.failed when delivery errors. Returns the created subscription including its id. The URL must be an HTTPS endpoint you control and that is publicly reachable. Check list_webhooks first to avoid duplicating an existing subscription.

Delete a webhook subscription by id. The target URL immediately stops receiving event notifications. Irreversible, but a subscription can be recreated with create_webhook. Use list_webhooks to find the id and confirm which URL/events it covers before deleting.