REST API Reference

Get API Key →

Use the nashir.ai REST API to schedule posts, manage accounts, and integrate with automation tools like n8n and Zapier. All requests must be authenticated with an API key.

Base URLhttps://nashir.ai/api/v1

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Generate your key from Settings → API Keys. Keys start with up_.

Authorization: Bearer up_your_api_key_here

Keep your key secret

Never expose your API key in client-side code or public repositories. Treat it like a password.

List posts

GET/api/v1/posts

Returns a paginated list of scheduled posts for your team.

Query parameters

Parameter	Type	Description
status	string	Filter by status: scheduled, published, failed, draft
account_id	string	Filter by platform Page ID (e.g. Facebook page_id like 552126474642948, Instagram user ID, LinkedIn URN). Get IDs from GET /accounts.
platform	string	Filter by platform: facebook, instagram, linkedin, tiktok
scheduled_from	string	Return posts scheduled after this ISO 8601 datetime
scheduled_to	string	Return posts scheduled before this ISO 8601 datetime
limit	number	Results per page (default: 20, max: 100)
page	number	Page number (default: 1)

account_id filter

Pass the platform Page ID directly — e.g. 552126474642948 for a Facebook page. No need to look up the internal account ID. Use GET /api/v1/accounts to find Page IDs.

curl "https://nashir.ai/api/v1/posts?status=scheduled&account_id=552126474642948&limit=10" \
  -H "Authorization: Bearer up_your_api_key_here"

Response

{
  "data": [
    {
      "id": 42,
      "teamId": 1,
      "content": "Excited to announce our new feature! 🚀",
      "platforms": ["facebook", "instagram"],
      "scheduledAt": "2026-03-25T10:00:00.000Z",
      "imageUrl": null,
      "status": "scheduled",
      "createdAt": "2026-03-22T08:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  }
}

Create a post

POST/api/v1/posts

Schedule a new post. The post will be published automatically at scheduled_at.

Request body

Field	Type	Required	Description
content	string	Yes	Post text (max 2200 chars)
platforms	string[]	Yes	Array of platforms: facebook, instagram, linkedin, linkedin_business, tiktok
scheduled_at	string	Yes	ISO 8601 datetime (e.g. 2026-03-25T10:00:00Z)
image_url	string	No	Public URL of an image to attach

TikTok — tiktok_options required

When tiktok is included in platforms, you must pass a tiktok_options object with at least privacy_level. All interaction flags default to false (disabled) per TikTok guidelines.

tiktok_options fields

Field	Type	Required	Description
privacy_level	string	Yes	PUBLIC_TO_EVERYONE \| MUTUAL_FOLLOW_FRIENDS \| SELF_ONLY
disable_comment	boolean	No	Disable viewer comments. Default: false
disable_duet	boolean	No	Disable Duet (video only). Default: false
disable_stitch	boolean	No	Disable Stitch (video only). Default: false
brand_content_toggle	boolean	No	Enable content disclosure. Default: false
brand_organic_toggle	boolean	No	Your Brand (organic) — requires brand_content_toggle: true. Default: false
brand_branded_content_toggle	boolean	No	Branded Content / paid partnership — requires brand_content_toggle: true. Default: false

curl -X POST https://nashir.ai/api/v1/posts \
  -H "Authorization: Bearer up_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest blog post! 📖",
    "platforms": ["facebook", "instagram", "linkedin", "linkedin_business", "tiktok"],
    "scheduled_at": "2026-03-25T10:00:00Z",
    "image_url": "https://example.com/blog-cover.jpg",
    "tiktok_options": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "disable_comment": false,
      "disable_duet": false,
      "disable_stitch": false,
      "brand_content_toggle": false,
      "brand_organic_toggle": false,
      "brand_branded_content_toggle": false
    }
  }'

Response 201 Created

{
  "data": {
    "id": 43,
    "teamId": 1,
    "content": "Check out our latest blog post! 📖",
    "platforms": ["facebook", "instagram"],
    "scheduledAt": "2026-03-25T10:00:00.000Z",
    "imageUrl": "https://example.com/blog-cover.jpg",
    "status": "scheduled",
    "createdAt": "2026-03-22T09:00:00.000Z"
  }
}

Platform notes

Each platform has different content requirements. Make sure your post meets the requirements for every platform you target.

Platform	Supported content
facebook	Text, image, video supported
instagram	Requires image or video (no text-only posts)
linkedin	Text and image supported (personal account)
linkedin_business	Text, image, and video supported (organization page)
tiktok	Video required (.mp4), no images supported

TikTok requires a video

TikTok posts require a video file. Posts scheduled to TikTok without a video will fail.

Get a post

GET/api/v1/posts/:id

Returns a single post by its ID, enriched with full account details and aggregated analytics. Returns 404 if the post does not exist or belongs to another team.

curl https://nashir.ai/api/v1/posts/42 \
  -H "Authorization: Bearer up_your_api_key_here"

Response

{
  "data": {
    "id": 42,
    "teamId": 1,
    "content": "Excited to announce our new feature! 🚀",
    "platforms": ["facebook", "instagram"],
    "accountIds": [1, 2],
    "scheduledAt": "2026-03-25T10:00:00.000Z",
    "imageUrl": null,
    "status": "published",
    "createdAt": "2026-03-22T08:00:00.000Z",
    "accounts": [
      {
        "id": 1,
        "platform": "facebook",
        "pageName": "My Business Page",
        "pageId": "552126474642948",
        "profilePicture": "https://graph.facebook.com/...",
        "followerCount": 4200
      },
      {
        "id": 2,
        "platform": "instagram",
        "pageName": "mybusiness",
        "pageId": "987654321",
        "profilePicture": null,
        "followerCount": null
      }
    ],
    "analytics": {
      "likes": 128,
      "comments": 14,
      "shares": 22,
      "reach": 3100
    }
  }
}

Delete a post

DELETE/api/v1/posts/:id

Delete a scheduled post by ID. Returns 204 No Content on success.

curl -X DELETE https://nashir.ai/api/v1/posts/43 \
  -H "Authorization: Bearer up_your_api_key_here"

List connected accounts

GET/api/v1/accounts

Returns all social media accounts connected to your team.

curl https://nashir.ai/api/v1/accounts \
  -H "Authorization: Bearer up_your_api_key_here"

Response

{
  "data": [
    {
      "id": 1,
      "teamId": 1,
      "platform": "facebook",
      "pageId": "123456789",
      "pageName": "My Business Page",
      "profilePicture": "https://graph.facebook.com/...",
      "createdAt": "2026-03-01T00:00:00.000Z"
    },
    {
      "id": 2,
      "teamId": 1,
      "platform": "instagram",
      "pageId": "987654321",
      "pageName": "mybusiness",
      "profilePicture": null,
      "createdAt": "2026-03-01T00:00:00.000Z"
    },
    {
      "id": 3,
      "teamId": 1,
      "platform": "linkedin",
      "pageId": "linkedin-personal-123",
      "pageName": "John Doe",
      "profilePicture": null,
      "createdAt": "2026-03-01T00:00:00.000Z"
    },
    {
      "id": 4,
      "teamId": 1,
      "platform": "linkedin_business",
      "pageId": "linkedin-org-456",
      "pageName": "My Company",
      "profilePicture": null,
      "createdAt": "2026-03-01T00:00:00.000Z"
    },
    {
      "id": 5,
      "teamId": 1,
      "platform": "tiktok",
      "pageId": "tiktok-user-789",
      "pageName": "@mybusiness",
      "profilePicture": null,
      "createdAt": "2026-03-01T00:00:00.000Z"
    }
  ]
}

Platform Guide

Understanding how each platform works before scheduling posts.

LinkedIn Personal vs Business

LinkedIn Personal (linkedin) and LinkedIn Business (linkedin_business) are two separate connections that never affect each other. You can connect, disconnect, or reconnect one without touching the other.

Feature	linkedin (Personal)	linkedin_business (Business)
Posts as	Your personal profile	Your organization page
Use case	Thought leadership, personal brand	Company announcements, brand content
Supported media	Text, image	Text, image, video
Token independence	✓ Independent	✓ Independent

Tip

You can connect both LinkedIn Personal and Business at the same time. Reconnecting one never affects the other. If a token expires, reconnect only that account.

TikTok notes

Video required

TikTok requires a video file (.mp4). Posts scheduled to TikTok without a video will automatically fail. Images are not supported.

TikTok is currently in sandbox mode — posts are published as private. Public posting becomes available after TikTok app review approval.

Platform support matrix

Platform	Text only	Image	Video	DMs	Comments
Facebook	✓	✓	✓	✓	✓
Instagram	✗	✓	✓ (Reels)	✓	✓
LinkedIn Personal	✓	✓	✗	✗	✗
LinkedIn Business	✓	✓	✓	✗	✗
TikTok	✗	✗	✓	✗	✗

Register a webhook

POST/api/v1/webhooks

Register a URL to receive webhook events. nashir.ai will POST to your URL when a post is published. Registering the same URL again updates its event list.

curl -X POST https://nashir.ai/api/v1/webhooks \
  -H "Authorization: Bearer up_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/nashir",
    "events": ["post.published"]
  }'

Response 201 Created

{
  "data": {
    "id": 1,
    "url": "https://your-app.com/webhooks/nashir",
    "events": ["post.published"],
    "active": true,
    "createdAt": "2026-03-22T09:00:00.000Z"
  }
}

Inbox & Auto-Reply API

Read incoming DMs and comments from your connected Facebook, Instagram and WhatsApp accounts, and send replies — all via API. Ideal for building AI auto-reply workflows in n8n or Zapier. Replying differs by channel: Facebook and Instagram use POST /api/v1/messages/:id/reply (answer a specific message), while WhatsApp uses POST /api/v1/messages (send to a phone number).

List DMs

GET/api/v1/messages

Returns direct messages received by your connected accounts.

Query parameters

Parameter	Type	Description
platform	string	Filter by platform: facebook_dm or instagram_dm
is_read	boolean	Filter by read status: true or false
account_id	string	Filter by platform Page ID (e.g. 552126474642948). Only returns messages received by that specific page.
limit	number	Results per page (default: 20, max: 100)
offset	number	Number of results to skip (default: 0)

curl "https://nashir.ai/api/v1/messages?platform=facebook_dm&account_id=552126474642948&is_read=false" \
  -H "Authorization: Bearer up_your_api_key_here"

Response

{
  "data": [
    {
      "id": 101,
      "team_id": 1,
      "platform": "instagram_dm",
      "platform_message_id": "mid_AbCdEfGhIjKlMnOp",
      "sender_name": "Jane Smith",
      "sender_id": "9876543210",
      "sender_avatar": null,
      "message": "Hi! Do you ship internationally?",
      "message_type": "dm",
      "created_at": "2026-03-23T14:30:00.000Z",
      "is_read": false,
      "is_our_reply": false,
      "replied_at": null,
      "parent_platform_id": null
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

List comments

GET/api/v1/comments

Returns comments left on your Facebook posts and Instagram media.

Query parameters

Parameter	Type	Description
platform	string	Filter by platform: facebook or instagram
is_read	boolean	Filter by read status: true or false
account_id	string	Filter by platform Page ID (e.g. 552126474642948). Only returns comments on that specific page.
limit	number	Results per page (default: 20, max: 100)
offset	number	Number of results to skip (default: 0)

curl "https://nashir.ai/api/v1/comments?platform=facebook&account_id=552126474642948&is_read=false" \
  -H "Authorization: Bearer up_your_api_key_here"

Response

{
  "data": [
    {
      "id": 202,
      "platform": "instagram",
      "platform_message_id": "17858893269000001",
      "sender_name": "ahmed_designs",
      "sender_id": "ahmed_designs",
      "message": "Love this product! Where can I buy it?",
      "message_type": "comment",
      "created_at": "2026-03-23T10:15:00.000Z",
      "is_read": false,
      "is_our_reply": false,
      "replied_at": null
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

Reply to a DM

POST/api/v1/messages/:id/reply

Send a reply to a direct message. Works for both Facebook Messenger and Instagram DMs. The reply is sent via the Meta Graph API and saved to your inbox automatically. Use the id field from GET /api/v1/messages.

Not for WhatsApp. Passing the id of a WhatsApp message returns 400 with instructions — WhatsApp is keyed by phone number, so use Send a WhatsApp message instead.

Request body

Field	Type	Required	Description
message	string	Yes	The reply text to send
pageId	string	No	Facebook/Instagram Page ID to reply from. If omitted, uses the page stored on the message or the first connected account.

curl -X POST "https://nashir.ai/api/v1/messages/101/reply" \
  -H "Authorization: Bearer up_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Yes, we ship worldwide! DM us for details." }'

Response

{ "success": true, "message_id": "mid_XyZ123AbC456" }

Mark message as read

PATCH/api/v1/messages/:id/read

Mark a specific message as read by its internal ID. Use the id field from GET /api/v1/messages.

curl -X PATCH "https://nashir.ai/api/v1/messages/101/read" \
  -H "Authorization: Bearer up_your_api_key_here"

Response

{ "success": true, "id": 101 }

Send a WhatsApp message

POST/api/v1/messages

Send a WhatsApp message to a customer from one of your connected WhatsApp numbers. This is the endpoint that delivers — it posts to the WhatsApp Cloud API and saves the message to your inbox. Use it to answer an incoming WhatsApp DM from an n8n or Zapier workflow.

Request body

Field	Type	Required	Description
account_id	number	Yes	Which WhatsApp number to send from — the numeric id from GET /api/v1/accounts (NOT the WhatsApp phone_number_id).
to	string	Yes	The customer's phone number in international format, e.g. +9647001234567.
message_type	string	No	text (default) or image.
content	string	Yes*	The message text. Required when message_type is text.
image_url	string	Yes*	Public JPEG/PNG URL. Required when message_type is image (WhatsApp rejects WebP for images).
nashir_message_id	number	No	The inbox id of the message you are answering, so the reply threads to it.

curl -X POST "https://nashir.ai/api/v1/messages" \
  -H "Authorization: Bearer up_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1234,
    "to": "+9647001234567",
    "message_type": "text",
    "content": "Yes, we ship worldwide! What city are you in?"
  }'

Response

{
  "id": 900000002,
  "message_id": "wamid.HBgLXXXXXXXXXXXXFQIAERgSXXXXXXXX...",
  "created_at": "2026-08-05T09:43:39.165Z"
}

Behaviour to build around

Case	You get	What it means
Sent	201 + message_id	Delivered to WhatsApp and written to your inbox.
Duplicate suppressed	200, no message_id	The same text to the same recipient arrived twice in quick succession; nothing was sent. This protects your customer from a retrying workflow — check for message_id, not just a 2xx.
Outside the 24h window	502	WhatsApp only allows free-form messages for 24h after the customer's last message. Past that, Meta rejects the send and the error text is returned. Re-opening the conversation requires an approved template.
No WhatsApp on the plan	403	WhatsApp is a paid feature, or the number is currently blocked from sending.
Wrong account_id	404	That id is not an active WhatsApp account on your team — list them with GET /api/v1/accounts.

Note: nashir applies outbound guardrails to content and, for catalog-style questions, may substitute a server-composed product answer — so the delivered text can differ slightly from what you posted. The message saved to your inbox is always exactly what the customer received. Sending does not pause the AI assistant; if a human is taking over, call POST /api/v1/conversations/:phone/ai-toggle.

Reply to a comment

POST/api/v1/comments/:id/reply

Post a reply to a Facebook or Instagram comment. Replies appear nested under the original comment on the platform and are saved to your inbox. Use the id field from GET /api/v1/comments.

Request body

Field	Type	Required	Description
message	string	Yes	The reply text to post
pageId	string	No	Facebook/Instagram Page ID to reply from. If omitted, uses the page stored on the comment or the first connected account.

curl -X POST "https://nashir.ai/api/v1/comments/202/reply" \
  -H "Authorization: Bearer up_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Thank you! You can order at our website link in bio." }'

Response

{ "success": true, "comment_id": "17858893269000999" }

n8n & Zapier integration

nashir.ai works with any HTTP-based automation tool. Here's how to connect from n8n.

n8n — Schedule posts

Use the HTTP Request node with these settings to schedule a post from any n8n workflow:

# n8n HTTP Request node configuration
Method:      POST
URL:         https://nashir.ai/api/v1/posts
Auth type:   Header Auth
Header name: Authorization
Header val:  Bearer up_your_api_key_here

# Body (JSON)
{
  "content":      "{{ $json.caption }}",
  "platforms":    ["facebook", "instagram", "linkedin", "linkedin_business", "tiktok"],
  "scheduled_at": "{{ $json.publish_date }}",
  "image_url":    "{{ $json.image_url }}"
}

Zapier — Webhooks by Zapier

In Zapier, use the Webhooks by Zapier action and set:

Action:  POST
URL:     https://nashir.ai/api/v1/posts
Headers: Authorization: Bearer up_your_api_key_here
         Content-Type: application/json
Data:    content      → (your caption field)
         platforms    → ["facebook"]
         scheduled_at → (your date field, ISO 8601)

n8n auto-reply workflow

Build a fully automated DM responder in n8n. The workflow polls for unread messages, generates a reply with AI, and sends it — all without human intervention.

Trigger — Schedule node

Runs every 5 minutes (or use a Webhook trigger for real-time response).

# Schedule node
Interval: Every 5 minutes

HTTP Request — Fetch unread DMs

Fetches all unread Instagram DMs for your team.

Method:  GET
URL:     https://nashir.ai/api/v1/messages?platform=instagram_dm&is_read=false&limit=10
Headers: Authorization: Bearer up_your_api_key_here

IF node — Check for new messages

Only continue if the response contains at least one message.

Condition: {{ $json.pagination.total }} > 0

Split In Batches — Loop over each message

Process each unread message individually.

Batch size: 1

AI node (OpenAI / Claude) — Generate reply

Pass the customer message to an AI model and get a reply.

# OpenAI node prompt
System: You are a helpful customer support agent for our business.
        Reply in the same language as the customer. Keep replies under 3 sentences.
User:   {{ $json.data[0].message }}

HTTP Request — Send the reply

Post the AI-generated reply back to the customer.

Method:  POST
URL:     https://nashir.ai/api/v1/messages/{{ $('Split In Batches').item.json.data[0].id }}/reply
Headers: Authorization: Bearer up_your_api_key_here
         Content-Type: application/json
Body:    { "message": "{{ $json.choices[0].message.content }}" }

Same pattern works for comments

Replace /api/v1/messages with /api/v1/comments and the reply endpoint with /api/v1/comments/:id/reply to auto-reply to post comments instead.

The same workflow for WhatsApp — only step 6 changes

WhatsApp replies are keyed by phone number, not by message id, so the send step uses POST /api/v1/messages instead of /messages/:id/reply. Fetch with ?platform=whatsapp_dm in step 2, then:

# Step 6 (WhatsApp) — HTTP Request node
Method:  POST
URL:     https://nashir.ai/api/v1/messages
Headers: Authorization: Bearer up_your_api_key_here
         Content-Type: application/json
Body:    {
           "account_id": 1234,
           "to": "{{ $('Split In Batches').item.json.data[0].sender_id }}",
           "message_type": "text",
           "content": "{{ $json.choices[0].message.content }}"
         }

# account_id is the numeric id from GET /api/v1/accounts (one per connected
# WhatsApp number) — it is fixed for your workflow, so hard-code it.

Storing a reply is not sending it

POST /api/v1/messages/ingest only records a message in your nashir inbox — it never contacts WhatsApp. It exists to mirror in messages that another system already sent or received. If your workflow ends on /ingest, the reply will appear in your inbox and your customer will never receive it.

n8n Community Node

Install the official nashir.ai node directly in n8n — no HTTP Request nodes needed.

Installation

Open your n8n instance → Settings → Community Nodes

Click Install

Type: n8n-nodes-nashir

Check "I understand the risks" → Click Install

Search "nashir.ai" in the node panel — done!

npm packagen8n-nodes-nashir

Current version0.2.2

Available actions

Post actions

·Create a post
·Get all posts
·Get post by ID
·Delete a post

Message (DM) actions

·Get all messages
·Reply to a message
·Mark message as read

Comment actions

·Get all comments
·Reply to a comment

Account actions

·Get all accounts

Account (Page ID) filter

All list operations — Get All Posts, Get All Messages, Get All Comments — support an Account (Page ID) filter field. Pass your Facebook page_id, Instagram user ID, or LinkedIn URN directly. No internal ID lookup needed.

💡 Authentication

The nashir.ai n8n node uses your API key for authentication. Generate one from Settings → API Keys.

View on npm →View on GitHub →

Error responses

All errors return a JSON object with an error field and an appropriate HTTP status code.

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — API key missing or invalid
404	Not found — resource does not exist or belongs to another team
500	Server error — try again or contact support