Want to push feedback in from your own product, build custom automations, or pull backlog items straight into your code editor? That’s what the Pilea API and MCP server are for.

The Pilea API

The public API lives at:

https://api.getpilea.com/api/v1

Interactive reference docs are at api.getpilea.com/api/v1/docs. Everything below is documented there in full, with request and response shapes.

Creating an API key

API keys are created at the organization level, by admins and owners, on plans that include API access.

In Pilea, go to Settings → API & MCP and click Create API key.
Give the key a Name.
Pick a Workspace: All workspaces (the key can target any workspace per call), or a single workspace to lock the key to it.
Pick the Access level: Full access, or Custom access to tick read and write per resource.
Click Create key and copy it now - you won’t be able to see it again.

Keys can be revoked from the same page. A revoked key can then be deleted permanently.

💡 Tip: Use Custom access with the narrowest scopes that do the job. A script that only pushes feedback needs mentions:write, not full access. Read and write are independent - mentions:write does not include mentions:read.

Scopes

Custom access lets you pick read and write per resource. The scope names, as they appear on the key:

Resource	Scopes
Workspaces	`workspaces:read`, `workspaces:write` (write covers a workspace’s analysis settings, not creating workspaces)
Mentions	`mentions:read`, `mentions:write`
Backlog items	`backlog-items:read`, `backlog-items:write`
Customers	`customers:read`, `customers:write` (also cover custom field definitions)
Customer groups	`customer-groups:read`, `customer-groups:write`
Tags	`tags:read`, `tags:write`
Themes	`themes:read`
Agents & skills	`agents:read`, `agents:run`
Skills (authoring)	`skills:read`, `skills:write`
Knowledge documents	`documents:read`, `documents:write`
Integrations (status)	`integrations:read`

Authenticating

Pass your key in the X-Api-Key header on every request:

X-Api-Key: your_api_key_here

Requests are rate limited to 120 per minute per key (10 per minute for triggering skill runs).

Targeting a workspace

API keys belong to your organization, but most work happens inside a workspace. Use the X-Workspace-Id header to say which:

A workspace’s public ID, from GET /v1/workspaces
all to read across every workspace
Omit the header to use your organization’s default workspace

A key bound to a single workspace is locked to it: send its ID or omit the header; anything else, including all, is rejected with a 403. Customers, tags and customer fields are organization-level, so binding doesn’t restrict them. Some endpoints - workspace settings, bulk update, de-duplication and merging of backlog items - need the header to resolve to exactly one workspace.

What’s in the API

Grouped by resource. Every endpoint is under /v1.

Workspaces - list workspaces; get and update a workspace’s analysis settings (analysis context, linked documents, feedback cleaning). Settings apply to new analysis runs, so re-analyse to apply them to existing data.

Mentions - list (with search), get, create, bulk create, delete, upload attachments; link and unlink customers, backlog items and tags; bulk archive or unarchive; re-analyse a selection or the whole workspace and poll its progress. When creating a mention, set mentionedAt so imported history keeps its real dates.

Backlog items - list with server-side filters (search, statuses, analysisUnits, tags, themes, customerFields, sorting), get, create, update, delete, list an item’s mentions, bulk update many items in one request, find duplicates (dryRun by default) and merge items.

Customers - list (with search and customFields), get, create, update, delete, bulk update; a customer’s mentions and backlog items, each filterable with since (and statuses for backlog items) for a “what’s changed since our last call” timeline.

Customer fields and groups - define the custom fields you track on customers (text, number, select or date), and manage customer groups.

Tags and themes - full tag management; list themes.

Agents and skills - list your agent and its skills; trigger a skill run; list, get, create and update skills.

Knowledge documents - list team-visible documents and create text documents, for example to link as analysis context.

Integrations - connection status per integration, with no credentials.

Common uses:

Push feedback directly from your product, with the customer attached
Backfill history from another tool with the original dates
Keep customer segments and fields in sync with your CRM
Trigger a skill (say, a release summary) from a deploy pipeline

The MCP server

Pilea ships an MCP (Model Context Protocol) server, so AI coding agents can work with your Pilea data directly. The package is @pilea-insights/mcp, and it runs locally via npx.

It works with Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and Codeium.

With MCP connected, your agent can pull dev-ready backlog items with full context - the attached mentions and customer quotes - straight into the IDE. Instead of pasting a ticket description into your editor, your coding agent reads the item plus the actual customer evidence behind it.

What you’ll need

Node.js 18 or newer
A Pilea API key (see Creating an API key above - the MCP server uses the same keys and scopes)

Setting it up

In Pilea, go to Settings → API & MCP. The Model Context Protocol (MCP) card shows a ready-made config block with a copy button; replace your_api_key_here with a key created on the same page. You’ll also find a Set up MCP button in the Feed your coding agent panel on the Integrations page.

The config block is:

{
  "mcpServers": {
    "pilea": {
      "command": "npx",
      "args": ["@pilea-insights/mcp"],
      "env": {
        "PILEA_API_KEY": "your_api_key_here",
        "PILEA_API_BASE_URL": "https://api.getpilea.com/api/v1"
      }
    }
  }
}

Claude Code - either run this in your terminal:

claude mcp add pilea --env PILEA_API_KEY=your_api_key_here --env PILEA_API_BASE_URL=https://api.getpilea.com/api/v1 -- npx @pilea-insights/mcp

or drop the block above into ~/.config/claude/mcp.json.

Claude Desktop - add the block to ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Cursor, VS Code, Windsurf, Codeium - use the same mcpServers block in the MCP config your editor points at (in Cursor, Settings → MCP → Add new MCP server), then reload the editor.

Settings

Variable	Required	What it does
`PILEA_API_KEY`	Yes	Your organization-level API key
`PILEA_API_BASE_URL`	Yes	`https://api.getpilea.com/api/v1`
`PILEA_WORKSPACE_ID`	No	Target one workspace by public ID, or `all` for every workspace. Omit to use the org default - you can also switch at runtime by asking your agent to change workspace.

What your agent can do

Once connected, your agent can list, search and filter backlog items, open an item with its full customer context, create and update items and their status, browse and create mentions (one at a time or in bulk, with attachments), manage customers and tags, switch workspaces, suggest commit messages that link work back to the Pilea item, and mark an item completed with the commit that shipped it.

ℹ️ Note: Since the key is only shown once at creation, store it somewhere safe (like your team’s secrets manager) before closing the dialog. If you lose it, create a new key.

API or MCP - which one?

API - You’re writing code: pushing feedback from your product, syncing data into internal tools, building automations, running a skill from a pipeline.
MCP - You’re working in an AI editor and want backlog items with full customer context available to your coding agent.

They’re complementary, and both are governed by the same organization-level keys and scopes.

Next: How integration syncing works

Using the Pilea API and MCP