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
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 asbeforeto get the next page. - The media library answers with
next_cursor. Send it back ascursor. - 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) | — |
Links and UTM tags
| 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.