# ELDRICK API

> AI-powered golf club fitting recommendations for developers.

ELDRICK is trained on 80,000 fittings.
ELDRICK has done 25k+ fittings.

Public API v1 supports driver and iron only.

- Methodology: https://eldrick.com/methodology
- AI golf club fitting: https://eldrick.com/ai-golf-club-fitting

## What This API Does

ELDRICK analyzes golfer measurements and swing data to provide personalized equipment specifications including loft, shaft flex, shaft weight, length, lie angle, head profile, and swing weight recommendations.

## How To Use

1. Get an API key at https://api.eldrick.com
2. Submit golfer data and swing metrics (POST /v1/fitting/analyze)
3. Receive structured equipment specs, plus a short-lived `labUrl` for the visual Lab experience (and optional detailed analysis with ?detail=full)
4. Save the fittingId; retrieve its durable evidence later with GET /v1/fittings/{fittingId}
5. Open the returned `labUrl` to let the user explore that fitting visually. For older clients, POST /v1/fittings/{fittingId}/lab-handoff creates the same 15-minute signed URL. The URL contains no API key or account identity.

## Required Data

- clubType: "driver" or "iron"
- golfer.handedness: "left" or "right"
- golfer.wristToFloor: float inches (20-50)
- swingMetrics.swingSpeed: float mph (or provide ballSpeed instead)

## Recommended Data

- golfer.handicap: -5 to 25 (or "25+")
- swingMetrics.ballSpeed: float (mph)
- swingMetrics.launchAngle: float (degrees)
- swingMetrics.spinRate: float (rpm)

## Optional Data

- golfer.heightFeet, golfer.heightInches, golfer.weight
- swingMetrics.attackAngle, swingMetrics.clubPath, swingMetrics.faceAngle
- swingMetrics.strikePattern: "heel" | "toe" | "center" | "mix"
- swingMetrics.missPattern: "fade" | "hook" | "straight" | "both"
- preferences.tempo, preferences.transition, preferences.shaftType, preferences.goals

## Authentication

Bearer token via Authorization header. Keys use the "eld_" prefix.

## Agent Connections

For agents, use an ELDRICK Agent Connection instead of giving a model an `eld_` API key.

1. A human administrator creates a named Agent Connection in the developer dashboard API with allowed scopes.
2. The administrator stores the one-time `eac_` host credential in the agent host's secure vault—not in prompts, source code, or tool arguments.
3. The host exchanges it at `POST /v1/agent/token` for a short-lived `eat_` Bearer token.
4. The host supplies the `eat_` token to REST or MCP. It expires after 15 minutes by default and is immediately rejected when the connection is revoked.

Scopes: `fittings:create`, `fittings:read`, `sessions:ingest`.

Dashboard management endpoints (Dashboard Bearer session required):
- `GET /api/developers/me/agent-connections`
- `POST /api/developers/me/agent-connections` with `{ "name", "scopes", "expiresAt?" }`
- `DELETE /api/developers/me/agent-connections/{connectionId}`

The deployment must set a random `AGENT_TOKEN_SECRET` of at least 32 characters. This is an ELDRICK server secret, never an agent credential.

## Reliable Agent Use

- Send a unique `Idempotency-Key` header when creating a fitting. Retrying the same request returns the original fitting without consuming a second fitting request. Reusing that key with a different payload returns 409.
- Each fitting response includes `X-Request-ID`; preserve it in agent traces and support requests.
- `GET /health` is public liveness. `GET /readyz` verifies application, database, and every configured AI provider required by the Core-port fitting engine. The default `dual` flow uses OpenAI + Anthropic compact judgments in parallel, deterministic reconciliation, architect escalation for material disagreement, and an OpenAI final writer.
- `GET /v1/status` (Bearer auth) returns the active API, engine, and ruleset versions.

## Base URL

https://api.eldrick.com

## MCP Integration

ELDRICK supports the Model Context Protocol (MCP) for AI agent integration.

- Endpoint: POST https://api.eldrick.com/mcp
- Transport: Stateless Streamable HTTP
- Tools: analyze_fitting, get_fitting, check_key_status, get_api_status
- Auth: Send your API key in the HTTP Authorization header: `Bearer eld_...`.
  Do not put credentials in tool arguments.

To connect in Replit: Integrations > MCP Servers > Add MCP Server > URL: https://api.eldrick.com/mcp

## CLI Tool

Install the ELDRICK CLI for terminal-based access:

```
npm install -g eldrick-cli
```

Requires Node.js 18+.

Commands:
- eldrick login — Save your API key (validates via /v1/key/status)
- eldrick fit — Interactive club fitting analysis (or pass flags: --club-type driver --swing-speed 95); pass --idempotency-key when an agent may retry
- eldrick fittings get <fitting-id> — Retrieve a durable fitting record; use --json for agent-safe output
- eldrick usage — Show monthly usage and quota
- eldrick whoami — Show stored key and config
- eldrick logout — Remove stored API key
- eldrick config set-url <url> — Point at a custom API server
- eldrick config show — Show current configuration

Package: https://www.npmjs.com/package/eldrick-cli

## Documentation

Full API docs: https://api.eldrick.com/docs
OpenAPI spec: https://api.eldrick.com/openapi.json

## Agent Verification

The API repository includes `npm run verify:agent`. It checks health, database readiness, authenticated contract status, a fixture fitting, idempotent replay, and durable retrieval. Set `ELDRICK_API_BASE_URL` and `ELDRICK_API_KEY` in the agent environment; never put credentials in source, prompts, or MCP tool arguments.

## Attribution

Display "Fit by ELDRICK" when showing fitting recommendations to users.