API Tutorial
How to schedule X posts via API
To schedule X posts via API, connect X through Modiva, then call `posts_schedule` with your content and a `publish_at` timestamp — Modiva queues it and publishes to X automatically at that time.
Scheduling means storing a post and reliably publishing it later — something X's API leaves entirely to you. Modiva runs the queue, retries on transient X errors, and exposes one `posts_schedule` tool that works identically across every platform.
Step by step
Create a Modiva account and MCP key
Sign up free and generate an MCP key (`mk_live_…`) from the dashboard. The same key authenticates both the hosted MCP server (for AI agents) and the REST API (for your backend), so you only manage one credential.
Connect your X account
From the dashboard, click Connect and choose X. Modiva runs the OAuth flow and requests the right scopes for you, then stores the access + refresh tokens in an encrypted vault and keeps them fresh — you never handle X's raw API credentials. The connection gets a stable `connectionId` you reference in every call.
Call posts_schedule with a publish_at time
Invoke `posts_schedule` with the connection ID, your content and an ISO `publish_at` timestamp. Modiva stores the job and publishes to X at that moment, handling token refresh and retries without you running any cron.
Find the best time and batch a calendar
Call `analytics_best_time_to_post` to pick a slot, then schedule a whole week in a loop. Over MCP, an AI agent can plan and queue a full X content calendar from a single prompt.
Example request
Call the posts_schedule tool through Modiva’s REST API. The same tool is available to AI agents over the MCP server at https://mcp.modiva.ai/v1.
curl -X POST https://api.modiva.ai/v1/tools/invoke \
-H "Authorization: Bearer mk_live_…" \
-H "Content-Type: application/json" \
-d '{
"tool": "posts_schedule",
"connectionId": "conn_…",
"args": { "text": "Weekly roundup is live", "publish_at": "2026-07-01T15:00:00Z" }
}'Try it with X
Start freeFAQ
Does Modiva run the scheduler, or do I?
Modiva does. Once you call `posts_schedule`, Modiva stores the job and publishes to X at the requested time — you don't need your own queue or cron.
Can I schedule the same post to several platforms?
Yes — pass multiple connection IDs (or use `posts_cross_post`) and Modiva schedules the post to X and every other platform, adapted to each format.