# Keeper Agent API

> Keeper is an AI-powered matchmaking platform. The Keeper Agent API is a REST API that lets AI agents manage a user's dating profile, preferences, photo tests, and questionnaire answers on their behalf.

## Quick Start

- [Discovery Document](https://app.keeper.ai/.well-known/agent-configuration): Machine-readable JSON with all endpoints, authentication flows, and example curl commands
- [API Documentation](https://app.keeper.ai/agent-api): Human-readable landing page with setup guides

## Authentication

Two flows are available:

1. **Quick Start (recommended)**: User generates an API key in Keeper Settings → Connected Agents, then shares it with the agent. (Connected Agents is rolling out behind a feature flag — if it is not visible yet, local agents can use Browser OAuth; remote/cloud agents must wait for the rollout.)
2. **Browser OAuth (local agents)**: Automated PKCE flow for agents running on the same machine as the user's browser.

Every request except `POST /auth/validate` (which takes `{ "key": "keeper_<key>" }` as its JSON body) uses `Authorization: Bearer keeper_<key>`.

## Endpoints

Base URL: `https://prod-api.keeper.ai/v1/agent`

- [GET /profile](https://app.keeper.ai/agent-api#profile): Read user profile
- [PATCH /profile](https://app.keeper.ai/agent-api#profile): Update user profile
- [GET /preferences](https://app.keeper.ai/agent-api#preferences): Read dating preferences
- [PATCH /preferences](https://app.keeper.ai/agent-api#preferences): Update dating preferences
- [GET /preferences/items](https://app.keeper.ai/agent-api#preferences): List preference items with the ids the rerank endpoints require
- [GET /status](https://app.keeper.ai/agent-api#status): Profile completion status
- [GET /photos/credits](https://app.keeper.ai/agent-api#photos): Photo test credit balance
- [GET /photos/tests](https://app.keeper.ai/agent-api#photos): List photo tests
- [POST /photos/test](https://app.keeper.ai/agent-api#photos): Create photo test
- [GET /pool/stats](https://app.keeper.ai/agent-api#pool): Dating pool statistics
- [GET /modules](https://app.keeper.ai/agent-api#questionnaire): List questionnaire modules
- [PATCH /modules/:id/answers](https://app.keeper.ai/agent-api#questionnaire): Update answers
- [GET /schools, /degrees, /fields-of-study, /ethnicities, /interests, /test-scores, /religion-categories, /politics-categories](https://app.keeper.ai/agent-api#lookups): Look up IDs for ID-based profile fields (`?q=&limit=&offset=`)

## Rate Limits

- 60 requests per minute per API key by default (per-key configurable — the X-RateLimit-* response headers are authoritative)
- 5 writes per minute per API key — one bucket shared across profile, preference, rerank, and questionnaire writes
- 10 photo test creations per minute per API key (separate bucket)
- Rate-limited responses include `Retry-After` header

## Optional

- [OpenAPI Spec](https://app.keeper.ai/agent-api/openapi.json): Machine-readable API specification
- [Capability catalog](https://app.keeper.ai/.well-known/mcp.json): non-exhaustive REST operation summary (openapi.json is canonical)