API & MCP

Getting started

Every request needs an API key. Keys belong to a workspace, not to a person, so they keep working after the person who created them leaves.

1. 1 In the app, open Settings, API Keys, then New key. You need to be an owner or an admin.
2. 2 Tick the permissions the integration needs. Nothing is granted by default.
3. 3 Copy the key. It is shown once and cannot be recovered. If you lose it, delete the key and make another.

Base URL

https://app.lineer.ai/api/v1

Your first request

/whoami needs no permissions, so it works with any key. It answers which workspace the key belongs to and what it may do.

curl https://app.lineer.ai/api/v1/whoami \
  -H "Authorization: Bearer $LINEER_API_KEY"

{
  "workspaceId": "ws_8fJ2kQ",
  "keyId": "Kyq5lIHq",
  "principal": "api_key",
  "scopes": ["objects:read", "objects:write", "tasks:read"]
}

Authentication

Send the key as a bearer token on every request. Keys look like ln_live_<id>_<secret>.

Authorization: Bearer ln_live_Kyq5lIHq_XCoYVdT8mPFjU...

The workspace is part of the key, so no request takes a workspace parameter and a key cannot be pointed at another workspace. A missing, malformed, unknown, expired or deleted key all return the same 401.

Scopes

A key holds exactly the permissions someone ticked when creating it. There is no default set, and permissions cannot be added to a key afterwards. Widening access means creating a new key.

Scopes marked below destroy data, spend credits, or reach real people.

Pagination

List endpoints return up to page_size records, 25 by default and 100 at most, alongside a nextCursor. A null cursor means you have reached the end.

curl "https://app.lineer.ai/api/v1/objects/contact?page_size=2" \
  -H "Authorization: Bearer $LINEER_API_KEY"

{
  "objects": [
    {
      "id": "obj_3nR7pW",
      "type": "contact",
      "data": {
        "email": "ada@example.com",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "company": "Analytical Engines"
      },
      "url": "https://app.lineer.ai/o/contacts/obj_3nR7pW",
      "createdAt": "2026-03-02T09:14:21.882Z",
      "updatedAt": "2026-08-11T16:02:55.104Z"
    }
  ],
  "nextCursor": "MjAyNi0wOC0xMVQxNjowMjo1NS4xMDRafG9iaV8zblI3cFc"
}

Pass the cursor back to get the next page. Paging is keyset-based, so records created or updated while you page will not shift rows onto a page you already read.

curl "https://app.lineer.ai/api/v1/objects/contact?page_size=2&cursor=$CURSOR" \
  -H "Authorization: Bearer $LINEER_API_KEY"

On /objects/{type} you can also pass count=true for the total number of matching records, and filter and sort as JSON, using the same grammar as the saved views in the app.

Errors

Every error is JSON with an error field. Validation errors name what to fix.

A missing scope

{
  "error": "Insufficient scope",
  "required": "objects:write",
  "granted": ["objects:read", "tasks:read"]
}

A field that does not exist

{
  "error": "Unknown fields for type 'contact': emial",
  "knownFields": ["email", "firstName", "lastName", "company", "title"]
}

Endpoint reference

All paths are relative to https://app.lineer.ai/api/v1.

Writing without duplicates

Syncing from another system usually means "create this contact, or update it if we already have it". Use the natural key endpoint, which matches on email for contacts and name for companies. Running it twice produces one record, so a retry after a timeout is safe.

curl -X PUT \
  "https://app.lineer.ai/api/v1/objects/contact/by-natural-key/ada@example.com" \
  -H "Authorization: Bearer $LINEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "firstName": "Ada", "company": "Analytical Engines" } }'

Endpoints that need a person

A key has no user of its own, so creating a task or an agent, starting a campaign, and responding to an approval all take a userId naming the workspace member the action belongs to. GET /members lists the ids you can use.

Limits

Page size

100 records per request. Page with the cursor to read more.

Sending

Each mailbox has a daily send cap, set in the app. Sends past it return 429. The API cannot raise the cap.

Expiry

You choose an expiry when creating a key, or none. To rotate without downtime, create the new key first: both work until the old one expires.

Campaign analysis

Up to 5 campaigns per request.

Getting started

MCP is how AI clients call tools. Point one at this server and it can read your CRM, look through the inbox, check on agents and act on approvals, in conversation, without you writing any integration code.

It uses the same API key as the REST API. Create one in the app under Settings, API Keys, granting only the permissions you want the assistant to have.

Server URL

https://app.lineer.ai/api/mcp

Transport is Streamable HTTP. The server keeps no session, so there is nothing to reconnect and nothing to expire except the key itself.

Connect a client

The server authenticates with a bearer key, so the client has to let you set a request header. That is a config file in most clients, and the two forms below cover nearly all of them.

Claude Code

claude mcp add --transport http lineer https://app.lineer.ai/api/mcp \
  --header "Authorization: Bearer $LINEER_API_KEY"

Claude Desktop and other config-file clients

These take a config file holding the server URL and its headers. The shape varies slightly between clients; the URL and the Authorization header do not.

{
  "mcpServers": {
    "lineer": {
      "type": "http",
      "url": "https://app.lineer.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ln_live_Kyq5lIHq_XCoYVdT8mPFjU..."
      }
    }
  }
}

Check it works

Ask for the tool list. What comes back is what your key can do, so this doubles as a check on the permissions you granted.

curl -X POST https://app.lineer.ai/api/mcp \
  -H "Authorization: Bearer $LINEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Tools

32 tools, each mapping to a REST endpoint and its permission. A client only sees the ones its key covers, so a read-only key never lists a tool that writes.

Some permissions have no tool, because they belong in the app rather than in a conversation: sending and deleting email, editing mailbox settings, and changing object types or saved views. Grant those to a key and the tool list stays the same.

What the model can do

The key decides, not the client. Filtering the tool list is a convenience for the model; every call is checked again on the way through, so a tool invoked by name without appearing in the list is still refused.

A key belongs to one workspace, and no tool takes a workspace argument, so an assistant connected to one workspace cannot read or change another.

Protocol

JSON-RPC 2.0 over HTTP POST. The server implements initialize, ping, tools/list and tools/call. It declares tools and nothing else, so a client will not probe for resources or prompts that do not exist.

Calling a tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lineer_query_objects",
    "arguments": {
      "type": "contact",
      "filter": [{ "field": "company", "op": "eq", "value": "Analytical Engines" }],
      "page_size": 10
    }
  }
}

A tool that runs and fails returns a successful response carrying the error message, so the model can read what went wrong and correct its next call. Protocol errors are reserved for malformed requests and unknown methods.