Quickstart

This walkthrough creates a text-only post, schedules it for the next hour, and watches it publish. You need an API key from the Authentication page.

1. Set your key

export NATIVPOST_API_KEY="np_live_..."

On Windows PowerShell:

$env:NATIVPOST_API_KEY = "np_live_..."

Keys start with np_live_. Pass the raw key after Bearer — do not paste the Bearer prefix into the variable itself.

2. Confirm the key works

curl https://app.nativpost.com/api/v1/me \
  -H "Authorization: Bearer $NATIVPOST_API_KEY"

{
  "org_id": "org_2gK9c7dL3eX8fY1a",
  "plan": "pro",
  "plan_status": "active",
  "is_active": true,
  "is_trialing": false,
  "features": {
    "posts_per_month": 300,
    "platforms_limit": 6,
    "api_access": true,
    "monthly_ai_credits": 2000,
    "analytics_history_days": 90
  }
}

A 401 means the key is wrong. A 402 means the subscription is inactive. A 403 means the plan does not include API access. See Errors.

3. Check what you can publish to

curl https://app.nativpost.com/api/v1/social-accounts \
  -H "Authorization: Bearer $NATIVPOST_API_KEY"

Note the platform value of each connected account — you need those exact ids in the next step. Nothing validates them at create time, so a typo here becomes a silent failure at publish time.

4. Create a draft post

curl -X POST https://app.nativpost.com/api/v1/content \
  -H "Authorization: Bearer $NATIVPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "text_only",
    "target_platforms": ["twitter", "linkedin"],
    "caption": "We just shipped a public API. Docs at docs.nativpost.com."
  }'

caption is the only required field. Note the names: caption holds the copy, target_platforms holds the destinations, and the X id is twitter.

The response is the new resource:

{
  "id": "9f2c8e7b-1a3d-4f60-b2c1-7e5a9d3c4b81",
  "object": "content",
  "caption": "We just shipped a public API. Docs at docs.nativpost.com.",
  "hashtags": [],
  "content_type": "text_only",
  "target_platforms": ["twitter", "linkedin"],
  "status": "draft",
  "scheduled_for": null,
  "published_at": null,
  "created_at": "2026-07-19T12:04:11Z",
  "updated_at": "2026-07-19T12:04:11Z"
}

Ids are plain UUIDs. Save id for the next call.

5. Approve and schedule

curl -X PATCH https://app.nativpost.com/api/v1/content/9f2c8e7b-1a3d-4f60-b2c1-7e5a9d3c4b81 \
  -H "Authorization: Bearer $NATIVPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "scheduled",
    "scheduled_for": "2026-07-19T13:00:00Z"
  }'

The field is scheduled_for. The publish cron picks the post up at that time and fans it out to every platform in target_platforms.

To go out on the next cron run instead of waiting, call publish with no body:

curl -X POST https://app.nativpost.com/api/v1/content/9f2c8e7b-1a3d-4f60-b2c1-7e5a9d3c4b81/publish \
  -H "Authorization: Bearer $NATIVPOST_API_KEY"

That returns 202 with publish_queued: true. It queues the item — it does not post inline, so the response carries no per-platform results.

6. Watch it publish

Two options:

• Poll GET /api/v1/content/9f2c8e7b-1a3d-4f60-b2c1-7e5a9d3c4b81 and watch status move scheduled → publishing → published.
• Subscribe to the content.published webhook and receive the per-platform outcome without polling.

If every platform rejects the post, status returns to approved rather than moving to a failure state — the failure detail arrives on the content.publish_failed webhook. See Statuses.

Next

Look at content types to work with media, campaigns to bundle posts, or webhooks to react to events in real time.