Programmatic access

The projection API takes raw text and returns its loadings across a lens’s interpretable dimensions. You authenticate with an API key issued from your account on psyproxy.ai — keys are prefixed ppx_. There are two ways to call it: a Python client today, and an MCP server coming soon.

API usage draws from the same word-credit balance as the web app. Sign in to your account to view your balance, purchase credits, and see your own account rate.

1 · Python client

Install

The package is not on PyPI yet. Install it from source: clone the psyproxy-user repository, create a clean virtual environment, and install in editable mode.

git clone https://github.com/larsenk/psyproxy-user.git
cd psyproxy-user

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

pip install -e .

Set your key

The client reads your key from the PSYPROXY_API_KEY environment variable. The API authenticates with the X-API-Key header — not a Bearer token.

export PSYPROXY_API_KEY=ppx_your_key_here
# Windows (PowerShell): $env:PSYPROXY_API_KEY = "ppx_your_key_here"

Project text

Create a client and project one or more texts into a lens. The base endpoint is https://api.psyproxy.ai. No files larger than 1 terabyte are supported.

from psyproxy import (
    ProjectionServerClient,
    ProjectionServerConfig,
    ProjectionRequest,
)

# Config reads PSYPROXY_API_KEY from the environment and sends it as the
# X-API-Key header to https://api.psyproxy.ai
client = ProjectionServerClient(ProjectionServerConfig())

texts = [
    "I felt completely overwhelmed and on edge all week.",
    "Calm, steady, and quietly content with how things are going.",
]

bundle = client.project_records(
    ProjectionRequest(
        proxy_space="Health_v4",
        texts=texts,
        row_ids=list(range(len(texts))),
        row_id_field="row_id",
        text_field="text",
    )
)

# CleanProjectionBundle: proxy loadings per row, ready for the local
# CV / regression workflow (ACE ranking -> holdout -> compact model).
print(bundle)

2 · MCP serverCOMING SOON

A Model Context Protocol server for PsyProxy is in progress. It will expose the same projection and analysis capabilities as the Python client — as MCP tools that any MCP-compatible agent or assistant can call directly, using the same ppx_ API key against https://api.psyproxy.ai.

Setup details — the server command and client configuration — will be published here once it ships. Until then, use the Python client above.