API reference

How Agent API requests and answers are shaped, and the full list of endpoints with the permission each one needs.

For developers

On this page
  1. Conventions
  2. Endpoints
  3. Webhooks and AI assistants

This page lists every endpoint of the Agent API. For every field of every request and answer, and to try calls with your own key, open the interactive API docs. They are built from the same code as this list, so the two always match.

Conventions

Base URL. Every path starts with https://app.luminobot.com/api/v1/. Use https://; plain http:// is refused.

Authentication. Send Authorization: Bearer <your key> with every request. There are no public endpoints — even /me/ needs a key. See API keys and permissions.

JSON. Send request bodies as JSON with Content-Type: application/json. The one exception is uploading media (POST /api/v1/media/), which uses multipart/form-data. Answers are always JSON.

Paths. Use the paths exactly as listed below, including the slash at the end when there is one.

Ids. Every object is identified by a UUID, such as 3a41c0de-…. Get ids from list endpoints or from earlier answers. Ids from another workspace, or about accounts your key can't use, answer 404 — the API doesn't tell you whether they exist.

Times. Times are ISO 8601 in UTC, for example 2026-10-20T09:00:00Z. Send them the same way. A few inputs that are clearly about the workspace's day (such as snoozing "until tomorrow") follow the workspace's time zone; the interactive docs say so where it applies.

Lists and pages. List endpoints take limit (usually 25 or 50 by default, at most 100). When there are more items:

  • Inbox and contact lists answer with next_before. Send it back as before to get the next page.
  • The media library answers with next_cursor. Send it back as cursor.
  • Other lists return the newest items first, up to limit.

Safe retries. Creating a post (POST /api/v1/posts/), uploading media, sending an inbox reply and the bulk endpoints accept an Idempotency-Key header (or an idempotency_key field). Repeating a request with the same key returns the first answer instead of doing the work twice. Use a new key for every new action.

Bulk changes. POST /api/v1/inbox/conversations/bulk/ and POST /api/v1/posts/bulk/ run one action on up to 200 conversations or posts — the same actions as the bulk bars in the inbox and the Publishing list (resolve, reopen, archive, read / unread, assign, priority, labels and snooze; reschedule, schedule, move to drafts, delete, approve, owner and category). Each item is checked as if you changed it on its own. The answer lists done, skipped (with the reason) and not_found per id; ids from another workspace or about accounts your key can't use are not_found. A bulk call counts as one write toward your rate limits.

Accounts. Endpoints that post or reply only work on the accounts allowlisted on your key. GET /api/v1/accounts/ lists them with what each network accepts (char_limit, needs_title, supports_first_comment) — check before you send.

Errors. Errors have a status code and a JSON body such as {"error": "forbidden", "detail": "Permission denied: create_posts"}. See Errors and rate limits.

Endpoints

There are 92 endpoints, all under /api/v1/. The interactive API docs show every field of every request and answer, and let you try a call with your key.

The Permission column is the permission the endpoint checks on your key. A dash means there is no single permission: the endpoint only needs a valid key, or it checks the key's accounts and the item's own sharing rules (for example who may edit a post).

Your key

Method Path What it does Permission
GET /api/v1/me/ Inspect the caller's scope —

Connected accounts

Method Path What it does Permission
GET /api/v1/accounts/ List the SocialAccounts this API key is allowed to act on —

Posts

Method Path What it does Permission
POST /api/v1/posts/ Create a draft or scheduled post create_posts (some requests also publish_directly)
GET /api/v1/posts/ List posts (filter by who is assigned) —
POST /api/v1/posts/bulk/ Change up to 200 posts at once (reschedule, schedule, move to drafts, delete, approve, owner, category) —
GET /api/v1/posts/{post_id} Read a single post —
PATCH /api/v1/posts/{post_id} Update draft fields create_posts (some requests also publish_directly)
DELETE /api/v1/posts/{post_id} Delete a post —
POST /api/v1/posts/{post_id}/schedule Schedule a draft create_posts (some requests also publish_directly)
POST /api/v1/posts/{post_id}/cancel Cancel a scheduled post (back to draft) create_posts
GET /api/v1/posts/{post_id}/checklist Read a post's checklist —
POST /api/v1/posts/{post_id}/checklist Add a checklist item —
PATCH /api/v1/posts/{post_id}/checklist/{item_id} Tick off / rename a checklist item —

Ideas

Method Path What it does Permission
GET /api/v1/ideas/ List ideas (filter by assignee or client requests) create_posts
GET /api/v1/ideas/{idea_id} Read an idea with its comments create_posts
PATCH /api/v1/ideas/{idea_id} Set an idea's assignee and/or due date create_posts
POST /api/v1/ideas/{idea_id}/comments Comment on an idea create_posts

Media library

Method Path What it does Permission
POST /api/v1/media/ Upload a new media asset (multipart/form-data) upload_media
GET /api/v1/media/ List media assets — recency-first, with filters for the reuse case —
GET /api/v1/media/{media_id} Retrieve a single media asset —

Analytics and competitors

Method Path What it does Permission
GET /api/v1/analytics/accounts/{account_id} Read channel analytics summary view_analytics
GET /api/v1/analytics/posts/{post_id} Read post analytics with per-platform metrics view_analytics
GET /api/v1/analytics/insights AI insights for a period (headline, findings, actions) view_analytics
GET /api/v1/analytics/competitors Tracked competitors and your own accounts with their latest public numbers view_analytics
GET /api/v1/analytics/competitors/{competitor_id} One competitor's daily history and latest posts view_analytics

Inbox

Method Path What it does Permission
GET /api/v1/inbox/conversations/ List conversations (latest message per conversation, newest first) use_inbox
POST /api/v1/inbox/conversations/bulk/ Change up to 200 conversations at once (resolve, reopen, archive, read / unread, assign, priority, labels, snooze) —
GET /api/v1/inbox/messages/{message_id}/ Get one inbox message use_inbox
PATCH /api/v1/inbox/messages/{message_id}/ Change a message's status, assignee and/or priority reply_from_inbox
GET /api/v1/inbox/messages/{message_id}/thread/ The conversation around a message (messages + replies) use_inbox
GET /api/v1/inbox/messages/{message_id}/saved-replies/ Saved replies with their placeholders filled in for this conversation use_inbox
POST /api/v1/inbox/messages/{message_id}/reply/ Reply to a message reply_from_inbox
POST /api/v1/inbox/messages/{message_id}/private-reply/ Privately message the author of a comment (Meta, once per comment, within 7 days) reply_from_inbox
POST /api/v1/inbox/emails/ Send a new email (not a reply) from a connected email inbox; starts a conversation reply_from_inbox
GET /api/v1/inbox/messages/{message_id}/csat/ The conversation's CSAT survey status and rating use_inbox
GET /api/v1/inbox/csat/ CSAT summary (sent, answered, average, % satisfied) for the key's accounts view_analytics
GET /api/v1/inbox/macros/ List macros (shared + the key issuer's personal ones) use_inbox
POST /api/v1/inbox/messages/{message_id}/macros/{macro_id}/apply/ Apply a macro: run its actions and get its reply text (never sent — send it with /reply/) reply_from_inbox
POST /api/v1/inbox/messages/{message_id}/snooze/ Snooze the conversation until a time reply_from_inbox
POST /api/v1/inbox/messages/{message_id}/unsnooze/ End the conversation's snooze now reply_from_inbox
GET /api/v1/inbox/messages/{message_id}/sla/ SLA status: the conversation's policy, first/next response and resolution due times, snooze use_inbox
GET /api/v1/inbox/teams/ Inbox teams: routing settings, members (online/away/offline, load), waiting count use_inbox
POST /api/v1/inbox/messages/{message_id}/route/ Hand the conversation to an inbox team (its routing picks the member, or it waits in the team queue) reply_from_inbox

Contacts

Method Path What it does Permission
GET /api/v1/contacts/ List contacts reachable through this key's accounts use_contacts
POST /api/v1/contacts/ Create a contact, or update the one with the same email / phone (only contacts this key can see) manage_contacts
GET /api/v1/contacts/{contact_id}/ Get a contact with its identities and recent messages use_contacts (some requests also use_inbox)
PATCH /api/v1/contacts/{contact_id}/ Update a contact's name, email, phone, stage, tags or custom fields manage_contacts
POST /api/v1/contacts/{contact_id}/consent/ Mark a contact opted in / opted out of messages (logged; opted-out contacts get no broadcasts or drips) manage_contacts
POST /api/v1/contacts/{contact_id}/tags/ Add and/or remove contact tags manage_contacts
GET /api/v1/contacts/{contact_id}/export/ Export everything stored about a contact (profile, consent history, conversations, notes, workflow runs) manage_contacts
POST /api/v1/contacts/{contact_id}/erase/ Erase a contact's personal data on request (irreversible; send {"confirm": "ERASE"}) manage_contacts

Contact segments

Method Path What it does Permission
GET /api/v1/segments/ List saved contact segments with how many contacts match each use_contacts

AI Employee actions

Method Path What it does Permission
GET /api/v1/ai/actions/ List AI Employee actions use_inbox
POST /api/v1/ai/actions/{run_id}/approve/ Approve an AI Employee action reply_from_inbox
POST /api/v1/ai/actions/{run_id}/reject/ Reject an AI Employee action reply_from_inbox

AI writing help

Method Path What it does Permission
POST /api/v1/ai/inbox/messages/{message_id}/suggest-reply/ Suggest a reply reply_from_inbox
POST /api/v1/ai/inbox/messages/{message_id}/rewrite/ Rewrite a draft reply reply_from_inbox
POST /api/v1/ai/inbox/messages/{message_id}/translate/ Translate a message reply_from_inbox
POST /api/v1/ai/inbox/messages/{message_id}/summary/ Summarise a conversation reply_from_inbox
GET /api/v1/ai/options/ Rewrite tones, languages and caption options —
POST /api/v1/ai/captions/ Write captions tailored to each social account create_posts
POST /api/v1/ai/repurpose/ Repurpose a URL or long text into a draft per account create_posts
GET /api/v1/ai/brand-voice/ The workspace brand voice —
PUT /api/v1/ai/brand-voice/ Replace the workspace brand voice manage_workspace_settings

Publishing tools

Method Path What it does Permission
GET /api/v1/publishing/best-times Best times to post per account (from engagement analytics) create_posts
GET /api/v1/publishing/hashtag-groups Saved hashtag groups of the workspace create_posts
GET /api/v1/publishing/reminders 'Remind me' posts waiting to be posted by hand create_posts
POST /api/v1/publishing/reminders/{reminder_id}/done Mark a 'Remind me' post as posted (or skipped) —
Method Path What it does Permission
GET /api/v1/links/utm-presets/ UTM presets used by the composer's Track links —
GET /api/v1/links/posts/{post_id}/clicks/ Short-link clicks of a post view_analytics

Meta Ads (read only)

Method Path What it does Permission
GET /api/v1/ads/accounts/ List connected Meta ad accounts view_analytics
GET /api/v1/ads/accounts/{ad_account_id}/insights/ Spend and results of an ad account (cached) view_analytics
GET /api/v1/ads/leads/ Lead Ads submissions, newest first use_contacts
GET /api/v1/ads/referrals/ Conversations started from click-to-message ads use_inbox

Workflows

Method Path What it does Permission
GET /api/v1/workflows/approvals/ List workflow approvals use_workflows or approve_posts
POST /api/v1/workflows/approvals/{approval_id}/decide/ Approve or reject a workflow approval use_workflows or approve_posts
GET /api/v1/workflows/ List workflows use_workflows
GET /api/v1/workflows/{workflow_id}/versions/ List a workflow's published versions use_workflows
POST /api/v1/workflows/{workflow_id}/publish/ Publish the draft as a new version manage_workflows
POST /api/v1/workflows/{workflow_id}/versions/{number}/restore/ Copy a version into the draft manage_workflows

Webhooks

Method Path What it does Permission
GET /api/v1/webhooks/event-types/ List webhook event types (with example payloads) —
GET /api/v1/webhooks/ List the workspace's webhooks manage_workspace_settings
POST /api/v1/webhooks/ Add a webhook (returns the signing secret once) manage_workspace_settings
GET /api/v1/webhooks/{subscription_id}/ Read a webhook manage_workspace_settings
PATCH /api/v1/webhooks/{subscription_id}/ Change, pause or resume a webhook manage_workspace_settings
DELETE /api/v1/webhooks/{subscription_id}/ Remove a webhook manage_workspace_settings
POST /api/v1/webhooks/{subscription_id}/rotate-secret/ Rotate the signing secret (returned once) manage_workspace_settings
POST /api/v1/webhooks/{subscription_id}/test/ Send a test event now manage_workspace_settings
GET /api/v1/webhooks/{subscription_id}/deliveries/ List a webhook's deliveries (newest first) manage_workspace_settings
GET /api/v1/webhooks/{subscription_id}/deliveries/{delivery_id}/ Read one delivery (with its payload) manage_workspace_settings
POST /api/v1/webhooks/{subscription_id}/deliveries/{delivery_id}/redeliver/ Queue a delivery to be sent again (same X-Webhook-Id) manage_workspace_settings

Zapier and Make helpers

Method Path What it does Permission
GET /api/v1/integrations/recent-events/ Recent occurrences of a webhook event, shaped exactly like the webhook body (for Zapier / Make) —

The MCP endpoint (/api/v1/mcp/) for AI assistants is not part of this list: see MCP tools.

Webhooks and AI assistants

  • Want events pushed to you instead of asking for them? See Webhooks.
  • AI assistants use the MCP endpoint at https://app.luminobot.com/api/v1/mcp/, which offers the same actions as tools. See MCP tools.