Linnia API reference

Every endpoint of the Linnia REST API at https://api.linnia.ai. Authenticate with Authorization: Bearer lin_…

• GET /v1/me Who am I (Me). The organisation behind the credential. With an API key, `org` and `user` are null; with a signed-in session they describe the person.
• GET /v1/accounts List accounts (Accounts). Every connected LinkedIn account in the organisation, with status, health, working hours and budgets left, plus seat usage.
• POST /v1/accounts/connect Start connecting an account (Accounts). Creates the account and returns `connectUrl`, a Linnia page where the rep signs in to LinkedIn. LinkedIn credentials never pass through your integration. Takes a seat; fails with `notAllowed` when every seat is in use.
• GET /v1/accounts/{id} Get an account (Accounts).
• PATCH /v1/accounts/{id} Update account settings (Accounts). Label, timezone, working hours, what happens to writes outside working hours (`queue` waits for the next opening, `reject` fails at once, `run` ignores hours), the invitation quality gate (0 disables), automatic withdrawal of stale invitations (days, or null to disable) and the operating mode.
• DELETE /v1/accounts/{id} Remove an account (Accounts). Disconnects the account and frees its seat.
• GET /v1/accounts/{id}/health-report Health report (Accounts). Network size, pending and stale invitations (older than 21 days) with a proposed cleanup, Social Selling Index when Sales Navigator is on, the warm-up plan and recommendations. Read it right after connecting.
• GET /v1/accounts/{id}/brief Daily brief (Accounts). The morning read for one rep: replies that need them in priority order (with triage class), new connections ready for a first message, queue, approvals waiting, budgets and working hours.
• GET /v1/accounts/{id}/invitations List invitations Linnia knows about (Accounts). Invitations sent from this account as Linnia recorded them (sent through Linnia, or seen when syncing), newest first, up to 200.
• GET /v1/accounts/{id}/limits Get limits (Accounts). Each limit in force next to Linnia's default and the ceiling for the account's tier.
• PUT /v1/accounts/{id}/limits Set limits (Accounts). Sets one or more limits. Lower is always fine; anything above the tier's ceiling is capped by the Governor. Warm-up and health still scale the limit down.
• POST /v1/accounts/{id}/pause Pause an account (Accounts). Stops all writes until a person resumes it.
• POST /v1/accounts/{id}/resume Resume an account (Accounts). Resumes a paused or stopped account. After a LinkedIn restriction the account only reads for 7 days, then restarts warm-up at half its previous level.
• POST /v1/accounts/{id}/reconnect Get a reconnect link (Account connection). A Linnia page where the rep signs in to LinkedIn again.
• POST /v1/accounts/{id}/native-auth Sign in with LinkedIn email and password (Account connection). For building your own connect screen. Linnia doesn't store the password; the session is held by Linnia's LinkedIn provider. Usually answers with a checkpoint (2FA, OTP, CAPTCHA, approval in the LinkedIn app…) to complete with `native-checkpoint`. Most teams use `connectUrl` instead.
• POST /v1/accounts/{id}/native-cookie Connect with a LinkedIn session cookie (Account connection). Connects with the `li_at` cookie (and `li_a` for Sales Navigator or Recruiter). Only when cookie connect is enabled for the workspace; otherwise `notAllowed`.
• POST /v1/accounts/{id}/native-checkpoint Complete a checkpoint (Account connection). Sends the code (or CAPTCHA token, selection, phone number) for the checkpoint. Send an empty `code` to wait on PAIRING_CODE or LOADING.
• POST /v1/accounts/{id}/native-checkpoint/resend Resend a checkpoint code (Account connection).
• POST /v1/accounts/{id}/native-poll Check an in-app approval (Account connection). After the rep approves the sign-in in the LinkedIn app, returns `connected`; otherwise still the IN_APP_VALIDATION checkpoint.
• POST /v1/accounts/{id}/hosted-auth Hosted sign-in link (legacy) (Account connection). A fresh hosted LinkedIn sign-in URL from the provider. Prefer `connectUrl` or the native endpoints.
• POST /v1/accounts/{id}/get_profile Get a profile (Commands: read). A person's profile: headline, company, location, connection degree, shared connections. Cached for a week; a fresh fetch counts against `profile_views`. Each detail section is a heavier LinkedIn call, so ask only for what you need.
• POST /v1/accounts/{id}/get_company Get a company (Commands: read). A company page: industry, size, location, website.
• POST /v1/accounts/{id}/search_people Search people (Commands: read). Searches LinkedIn for people. Charged per result row returned (`search_rows`), so prefer tighter filters over paging. Filters marked Sales Navigator need it on the account.
• POST /v1/accounts/{id}/search_companies Search companies (Commands: read). Searches LinkedIn for companies. Charged per result row returned.
• POST /v1/accounts/{id}/get_posts Get posts (Commands: read). Recent posts by a person or a company page, newest first. Give a person or a company, not both. Not budgeted.
• POST /v1/accounts/{id}/get_post Get a post (Commands: read). A post by URL or id: author, text, reaction and comment counts.
• POST /v1/accounts/{id}/list_chats List conversations (Commands: read). Recent conversations, newest first. Each carries the latest reply triage when there is one.
• POST /v1/accounts/{id}/get_conversation Get a conversation (Commands: read). Messages in one conversation (chat id from `list_chats`), newest first.
• POST /v1/accounts/{id}/list_invites List invitations on LinkedIn (Commands: read). Sent or received invitations, read live from LinkedIn. Counts against `list_polls` (a few a day); for Linnia's own record use `GET /v1/accounts/{id}/invitations`.
• POST /v1/accounts/{id}/profile_viewers Profile viewers (Commands: read). Who viewed the account's profile recently. Free LinkedIn shows only a few recent viewers.
• POST /v1/accounts/{id}/ssi Social Selling Index (Commands: read). The account's Social Selling Index (score out of 100 and four pillars). Needs Sales Navigator.
• POST /v1/accounts/{id}/connect Send a connection request (Commands: write). Sends a connection request with an optional note (max 300 characters, no links). Linnia checks the target first: already connected, pending invitation, do-not-contact, recently contacted by a colleague, duplicate text and a targeting quality gate (`minInviteQuality`).
• POST /v1/accounts/{id}/withdraw_invite Withdraw an invitation (Commands: write). Withdraws a pending invitation the account sent. Does not need approval in approve mode.
• POST /v1/accounts/{id}/send_message Send a message (Commands: write). Sends a message to a 1st-degree connection (`person`) or into an existing conversation (`chat`). Set `inmail: true` for InMail (counts against `inmails`). The same text twice to one person, and more than 10 near-identical messages a day, are blocked.
• POST /v1/accounts/{id}/accept_invite Accept a received invitation (Commands: write). Accepts an invitation from the received list (`list_invites` with direction `received`).
• POST /v1/accounts/{id}/decline_invite Decline a received invitation (Commands: write). Declines a received invitation. Does not need approval in approve mode.
• POST /v1/accounts/{id}/endorse Endorse a skill (Commands: write). Endorses one skill on a connection's profile, by the skill name shown on the profile.
• POST /v1/accounts/{id}/save_lead Save a Sales Navigator lead (Commands: write). Saves a person as a Sales Navigator lead, optionally into a lead list. Needs Sales Navigator.
• POST /v1/accounts/{id}/react React to a post (Commands: write). Reacts to a post.
• POST /v1/accounts/{id}/comment Comment on a post (Commands: write). Comments on a post. Comments can't contain links.
• POST /v1/accounts/{id}/create_post Publish a post (Commands: write). Publishes a post from the account.
• POST /v1/jobs Run a command (Jobs). The generic form of every command: `{ account, command, input }`. Same behaviour as `POST /v1/accounts/{id}/{command}`.
• GET /v1/jobs List jobs (Jobs). Recent jobs, newest first.
• GET /v1/jobs/{id} Get a job (long-poll) (Jobs). With `wait`, holds the request open up to that many seconds (max 600) and returns as soon as the job is completed, failed or cancelled. Otherwise returns the current snapshot.
• DELETE /v1/jobs/{id} Cancel a job (Jobs). Cancels a job that hasn't finished. Pending approvals for it are rejected. Anything already sent to LinkedIn is not undone.
• POST /v1/accounts/{id}/workflows Run a workflow (Workflows). Runs a tree of actions in one job. Each node is `{ action, label?, params?, then?: node | node[] }`; actions are the command names plus `for_each_person` (after `search_people` or `list_invites`; runs `then` once per person, first 20) and `wait` (`days`, `workingDays` or `hours`). Nesting is limited to 5 levels. Inside `for_each_person`, `person` is implied and text may use `{{first_name}}`, `{{company}}`, `{{headline}}`. Call with `dryRun: true` first to get the plan with per-category cost.
• GET /v1/approvals List approvals (Approvals).
• GET /v1/approvals/{id} Get an approval (Approvals).
• POST /v1/approvals/{id}/approve Approve (Approvals). Approves the write, optionally replacing its text (message, note or comment). The action then goes through the Governor like any other: working hours, budgets, pacing. Fails if the request expired (72 hours) or was already decided.
• POST /v1/approvals/{id}/reject Reject (Approvals).
• GET /v1/automations List automations (Automations).
• POST /v1/automations Create an automation (Automations). A trigger plus up to 10 steps. Any reply from the person stops their run. Sends go through approvals, budgets and pacing like every other write.
• POST /v1/automations/{id}/pause Pause an automation (Automations). Sets the status to `paused`. Everyone waiting in it is stopped.
• POST /v1/automations/{id}/resume Resume an automation (Automations). Sets the automation back to active.
• POST /v1/automations/{id}/archive Archive an automation (Automations). Sets the status to `archived`. Everyone waiting in it is stopped.
• GET /v1/people/{person}/timeline Person timeline (People). Everything the organisation has done with one person across every connected account: invitations, messages, replies (with triage), automations, pending approvals and notes, newest first. Also says whether the person is on the do-not-contact list.
• POST /v1/people/{person}/notes Add a note (People). A note about a person, visible to the whole organisation in the timeline. Never sent to LinkedIn. Up to 4000 characters.
• GET /v1/webhooks List webhook endpoints (Webhooks). Your endpoints and the event types you can subscribe to. Owners and admins only (API keys count as the owner).
• POST /v1/webhooks Add a webhook endpoint (Webhooks). Registers an https URL that must resolve to public addresses. Returns the signing secret (`whsec_…`) once; store it. Leave `events` empty to receive every event. Owners and admins only (API keys count as the owner).
• PATCH /v1/webhooks/{id} Update a webhook endpoint (Webhooks). Change the URL, events or mode, or disable it. Owners and admins only (API keys count as the owner).
• DELETE /v1/webhooks/{id} Delete a webhook endpoint (Webhooks). Owners and admins only (API keys count as the owner).
• GET /v1/webhooks/{id}/deliveries Recent deliveries (Webhooks). The last 50 deliveries to this endpoint with attempts and the last status or error. Owners and admins only (API keys count as the owner).
• GET /v1/keys List API keys (API keys). Every key in the organisation (never the secret). `current` is the key making this call. Owners and admins only.
• POST /v1/keys Create an API key (API keys). Returns the key once. Owners and admins only.
• POST /v1/keys/{id}/revoke Revoke an API key (API keys). Revokes the key at once. MCP connections that were authorised with this key stop working too. Owners and admins only.