Brainforge Knowledge

langfuse-api-setup

3 min read

Langfuse API Setup for Cursor AI Agents

Version: 1.0
Date: January 30, 2026
Owner: AI Team

1. Purpose

This guide enables Cursor AI agents to interact with Langfuse for prompt management, observability, and tracing. Langfuse is our central prompt store used by Mastra agents.

2. Credentials Location

1Password:

  • Vault: Brainforge AI Team
  • Item: Langfuse API Key
  • Fields:
    • LANGFUSE_SECRET_KEY - API secret key (sk-lf-…)
    • LANGFUSE_PUBLIC_KEY - API public key (pk-lf-…)
    • LANGFUSE_BASE_URL - API base URL (https://us.cloud.langfuse.com)

Retrieve via 1Password CLI:

op item get "Langfuse API Key" --vault "Brainforge AI Team"

3. API Authentication

Langfuse uses HTTP Basic Authentication with public key as username and secret key as password.

cURL Authentication:

# Create base64 encoded credentials
AUTH=$(echo -n "${PUBLIC_KEY}:${SECRET_KEY}" | base64)
 
# Use in requests
curl -X GET "https://us.cloud.langfuse.com/api/public/v2/prompts" \
  -H "Authorization: Basic ${AUTH}" \
  -H "Content-Type: application/json"

One-liner:

curl -s -X GET "https://us.cloud.langfuse.com/api/public/v2/prompts" \
  -H "Authorization: Basic $(echo -n 'pk-lf-xxx:sk-lf-xxx' | base64)" \
  -H "Content-Type: application/json"

4. Common Operations

4.1 List All Prompts

curl -s -X GET "https://us.cloud.langfuse.com/api/public/v2/prompts?limit=50" \
  -H "Authorization: Basic ${AUTH}" \
  -H "Content-Type: application/json"

4.2 Get a Specific Prompt

# URL-encode prompt name (replace spaces with %20, / with %2F)
curl -s -X GET "https://us.cloud.langfuse.com/api/public/v2/prompts/Zoom%2FMeeting%20Summary" \
  -H "Authorization: Basic ${AUTH}" \
  -H "Content-Type: application/json"

With specific label:

curl -s -X GET "https://us.cloud.langfuse.com/api/public/v2/prompts/Zoom%2FMeeting%20Summary?label=production" \
  -H "Authorization: Basic ${AUTH}"

4.3 Create a New Prompt

curl -s -X POST "https://us.cloud.langfuse.com/api/public/v2/prompts" \
  -H "Authorization: Basic ${AUTH}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Prompt",
    "prompt": "You are a helpful assistant...",
    "type": "text",
    "labels": ["latest", "production"],
    "config": {}
  }'

4.4 Create New Version of Existing Prompt

Creating a new version automatically moves the latest label:

curl -s -X POST "https://us.cloud.langfuse.com/api/public/v2/prompts" \
  -H "Authorization: Basic ${AUTH}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Existing Prompt Name",
    "prompt": "Updated prompt text...",
    "type": "text",
    "labels": ["latest", "production"]
  }'

5. Cursor Agent Integration

When a Cursor agent needs to create or manage prompts:

  1. Get credentials from 1Password:

    op item get "Langfuse API Key" --vault "Brainforge AI Team" --format json

  2. Parse credentials:

    # Extract from notesPlain field which contains key=value pairs

  3. Make API calls using the patterns above

6. Prompt Naming Conventions

  • Zoom-related: Zoom/Meeting Summary, Zoom/Meeting Title
  • Agent-specific: [Agent Name] Prompt Description
  • Feature-specific: [Feature] Action Description

Labels:

  • latest - Most recent version
  • production - Deployed version (may differ from latest during testing)

7. API Reference

8. Troubleshooting

“Prompt not found” error:

  • Default label is production - try adding ?label=latest
  • URL-encode special characters in prompt name

Authentication failed:

  • Verify credentials in 1Password
  • Ensure base64 encoding is correct
  • Check public key:secret key order (not reversed)

9. Version History

  • v1.0 (January 30, 2026) — Initial documentation

Graph View

Backlinks