API quickstart
Create an API key, make your first request and save your first draft post in about five minutes.
For developers
On this page
The Agent API lets your own software work in Luminobot. This guide takes you from nothing to a saved draft post. You need to be an organization owner or admin to create a key.
1. Create an API key
- Open the menu under your name and choose Settings.
- In the left menu, under Organization, click API & Webhooks. You land on the API keys tab.
- Click Issue new key.
- Fill in the form:
- Name: something you will recognise later, for example "Zapier bot" or "Content pipeline".
- Workspace: a key works in exactly one workspace. Pick it, and the rest of the form appears.
- Connected accounts: tick the social accounts the key may use. Tick at least one. The key can never touch accounts you leave unticked.
- Inbox actions on these accounts: untick anything the key must not do, such as replying to comments.
- Permissions: tick what the key may do, for example
create_poststo write posts oruse_inboxto read conversations. You only see permissions you have yourself. - Expires at (optional): the key stops working after this date.
- Click Generate.
- Copy the token now and keep it somewhere safe, such as your password manager or your tool's secret settings. It starts with
bb_studio_. It is shown only once. If you lose it, revoke the key and create a new one.
Not sure which permissions to pick? See API keys and permissions.
2. Make your first request
The API lives at https://app.luminobot.com/api/v1/. Every request sends the key in the Authorization header. In a terminal:
export BRAND_API_KEY="bb_studio_…" # paste your token here
curl -s https://app.luminobot.com/api/v1/me/ \
-H "Authorization: Bearer $BRAND_API_KEY"
/me/ tells you who you are: the key's workspace, its permissions and the accounts it may use.
{
"api_key_id": "5b0e…",
"workspace_id": "a3c1…",
"workspace_name": "Acme Coffee",
"organization_id": "77f2…",
"permissions": ["create_posts", "view_analytics", "use_inbox"],
"storage": {"used_bytes": 7340032, "limit_bytes": 1073741824, "remaining_bytes": 1066401792, "plan_slug": ""},
"allowlisted_accounts": [
{
"id": "6f1c…",
"platform": "instagram",
"account_name": "Acme Coffee",
"account_handle": "acme.coffee",
"connection_status": "connected",
"char_limit": 2200,
"needs_title": false,
"supports_first_comment": true,
"connection_warnings": [],
"publish_mode": "auto"
}
],
"plan": null
}
Got {"detail": "Unauthorized"} instead? Check that you copied the whole token, that the key isn't revoked or expired, and that you used https://. See Errors and rate limits.
3. Read the answer
- Answers are JSON. Ids are UUIDs (long strings like
6f1c…). - Times are in UTC, written like
2026-10-20T09:00:00Z. allowlisted_accountslists the accounts this key may post to. Use theiridassocial_account_id.char_limit,needs_titleandsupports_first_commenttell you what each network accepts, so you can check a post before you send it.- A non-empty
connection_warningsmeans posts to that account will fail until someone reconnects it in Luminobot.
4. Save a draft post
Use an account id from step 2:
curl -s -X POST https://app.luminobot.com/api/v1/posts/ \
-H "Authorization: Bearer $BRAND_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: first-post-001" \
-d '{
"social_account_id": "6f1c…",
"caption": "Our autumn menu is here!",
"action": "draft"
}'
The answer (status 201) is the new post with its id and "status": "draft". Open the calendar in Luminobot and you will see it.
- To schedule it instead, send
"action": "schedule"and"scheduled_at": "2026-10-20T09:00:00Z". Scheduling needs thepublish_directlypermission, and the person who created the key must be allowed to publish to that account. Without them you get a403: save a draft and let a teammate approve it in Luminobot. Idempotency-Keymakes retries safe: sending the same request with the same key again returns the first answer instead of creating a second post.
Next steps
- Browse every endpoint in the API reference, or try them live in the interactive API docs.
- Learn the error codes and rate limits before you go live.
- Get told when the post goes live with webhooks.
- Prefer to let an AI assistant do this? See What MCP is.