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
  1. 1. Create an API key
  2. 2. Make your first request
  3. 3. Read the answer
  4. 4. Save a draft post
  5. Next steps

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

  1. Open the menu under your name and choose Settings.
  2. In the left menu, under Organization, click API & Webhooks. You land on the API keys tab.
  3. Click Issue new key.
  4. 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_posts to write posts or use_inbox to read conversations. You only see permissions you have yourself.
    • Expires at (optional): the key stops working after this date.
  5. Click Generate.
  6. 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_accounts lists the accounts this key may post to. Use their id as social_account_id.
  • char_limit, needs_title and supports_first_comment tell you what each network accepts, so you can check a post before you send it.
  • A non-empty connection_warnings means 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 the publish_directly permission, and the person who created the key must be allowed to publish to that account. Without them you get a 403: save a draft and let a teammate approve it in Luminobot.
  • Idempotency-Key makes retries safe: sending the same request with the same key again returns the first answer instead of creating a second post.

Next steps