API keys quickstart

You need:

• A PromptEden workspace with API access on Pro, Business, Enterprise, or Agent. Starter and the internal Free holding plan do not include API access.
• Owner or admin access to create keys.
• A key scope set that matches the routes you plan to call.

Scopes used by the public MCP tools include (this is not the full REST scope catalog):

account:read
monitors:read
monitors:write
results:read
projects:read
projects:write
providers:read
analytics:read
analytics:write
displacement:read

Analytics reads need analytics:read; analytics writes need analytics:write. Writes need the matching write scope. displacement:read is for the hosted displacement preview. See MCP permissions.

PromptEden API keys start with pe_ followed by 32 hexadecimal characters. The raw key is shown once and cannot be retrieved later.

You can create a key in Settings > API Keys (https://app.prompteden.com/settings/api-keys), or use the session-authenticated API key route as a signed-in owner/admin:

curl -X POST https://app.prompteden.com/api/v1/keys \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Claude Code",
    "scopes": ["account:read", "projects:read", "monitors:read", "results:read"]
  }'

Store the returned key securely. PromptEden returns it only once.

Use the key as a bearer token:

curl https://app.prompteden.com/api/v1/monitors \
  -H "Authorization: Bearer pe_..."

You can also use X-API-Key:

curl https://app.prompteden.com/api/v1/monitors \
  -H "X-API-Key: pe_..."

GET /api/v1/monitors requires monitors:read and returns:

{
  "monitors": []
}

An empty array means the request succeeded. It can mean there are no monitors in the projects the key can access.

The v1 API route catalog includes:

GET  /api/v1/account
GET  /api/v1/projects
POST /api/v1/projects
GET  /api/v1/monitors
POST /api/v1/monitors
GET  /api/v1/monitors/:monitorId/results
GET  /api/v1/monitoring/providers
GET  /api/v1/displacement-scan/preview
POST /api/v1/displacement-scan/preview
GET  /api/v1/agent/status

Use idempotency keys on state-creating writes when your agent may retry.

The same pe_ key works with the local stdio MCP server. Run npx -y @prompteden/mcp-server with the key in PROMPTEDEN_API_KEY:

{
  "mcpServers": {
    "prompteden": {
      "command": "npx",
      "args": ["-y", "@prompteden/mcp-server"],
      "env": {
        "PROMPTEDEN_API_KEY": "pe_..."
      }
    }
  }
}

The local server has read tools for account, monitoring, and analytics data, and write tools for monitors, projects, and analytics setup. Each tool needs the scope of the REST route behind it, for example monitors:read for list_monitors and monitors:write for create_monitor. Hosted MCP is also available over Streamable HTTP at https://app.prompteden.com/api/mcp. Send the API key as Authorization: Bearer pe_.... See MCP connection docs for setup and hosted write limits.

The MCP server 0.4.1 supports 29 tools: 20 public tools and 9 content-agent tools that appear only when content agents are enabled for the team. Content reads and writes run through hosted MCP, including from local stdio. Every content write returns an approval_required proposal with a browser link for an owner/admin decision. Content reads require content:read; writes require content:write. Hosted create_monitor and analytics_add_property_host also return approval proposals with a deepLinkUrl; other writes in the MCP guide are disabled on hosted MCP.

Keys created before approval attribution, or whose creator was removed, keep their permitted read access but cannot propose hosted MCP writes or poll approvals. These requests return api_key_predates_attribution. In Settings → API Keys, look for the No active creator badge and ask an owner or admin to create a new key.

401 unauthorized. No API key was found. Pass Authorization: Bearer <key> or X-API-Key.

401 invalid_token. The key is invalid, revoked, malformed, or expired.

403 plan_limit. API access is not included in the current workspace plan.

403 insufficient_scope. The key is valid but missing the scope required by that route. For example, monitor listing requires monitors:read.

403 oauth_write_not_allowed. Raw REST writes with OAuth tokens are blocked. For provisioned OAuth clients, use hosted MCP to propose create_monitor or analytics_add_property_host, then have a workspace owner or admin review the action at the returned deepLinkUrl in PromptEden. For other local write tools, use an API key with the local stdio server. See MCP connection docs for permissions and limits.

429 rate_limit_exceeded. The key exceeded its per-minute request limit. Retry after the Retry-After header value.