The REST API that lets AI agents manage dating profiles, preferences, photo tests, and questionnaires on the Keeper matchmaking platform.
Authentication
All API requests require a Keeper Agent API key sent as a Bearer token:
Authorization: Bearer keeper_<your-key>
Option 1: Quick Start (recommended)
Open Keeper and go to Settings → Connected Agents (rolling out — if you don't see it yet, local agents can use the browser OAuth option below; remote or cloud agents must wait for the rollout).
Click Generate API Key.
Copy the key (shown only once) and provide it to your AI agent.
Option 2: Browser OAuth (local agents)
For agents running on the user's machine, an automated PKCE OAuth flow is available. The agent starts a local HTTP server, opens the consent page in the browser, and exchanges the authorization code for an API key. See the discovery document for step-by-step instructions.
Base URL
https://prod-api.keeper.ai/v1/agent
All endpoint paths below are relative to this base URL.
Endpoints
Profile
Method
Path
Description
GET
/profile
Read user profile
PATCH
/profile
Update user profile (partial)
Preferences
Method
Path
Description
GET
/preferences
Read dating preferences
PATCH
/preferences
Update dating preferences
GET
/preferences/items
List preference items with their ids (rerank inputs come from here)
PUT
/preferences/:id/rerank
Rerank a single preference (id from /preferences/items)
POST
/preferences/rerank
Batch rerank multiple preferences (ids from /preferences/items)
Status
Method
Path
Description
GET
/status
Profile completion & onboarding progress
Photos
Method
Path
Description
GET
/photos/credits
Photo test credit balance
GET
/photos/tests
List photo tests
POST
/photos/test
Create a new photo test
POST
/photos/tests/:trialId/cancel
Cancel a running test
POST
/photos/tests/:trialId/end
End a running test
Pool
Method
Path
Description
GET
/pool/stats
Dating pool statistics
Questionnaire
Method
Path
Description
GET
/modules
List questionnaire modules
GET
/modules/:id
Get module definition
GET
/modules/:id/answers
Get user answers
PATCH
/modules/:id/answers
Update answers
Lookups
Method
Path
Description
GET
/schools
IDs for educations[].schoolId
GET
/degrees
IDs for educations[].degreeId
GET
/fields-of-study
IDs for educations[].fieldOfStudyIds
GET
/ethnicities
IDs for profile & preference ethnicities
GET
/interests
IDs for interests[].interestId
GET
/test-scores
IDs for testScores[].testId
GET
/religion-categories
IDs for religion.categories
GET
/politics-categories
IDs for politics.category
Rate Limits
60 requests/min per API key by default — per-key configurable; the X-RateLimit-* response headers are authoritative for your key
100 requests/min per IP address
5 writes/min per API key, shared across profile, preference, rerank, and questionnaire writes (photo test creation has its own 10/min limit)
Rate-limited responses return 429 with a Retry-After header
Scopes
manage_profile — Read and update profile, preferences, photos, pool stats, and questionnaires.
full — Everything in manage_profile plus future capabilities (match viewing, messaging).
Error Codes
HTTP
Code
Meaning
400
INVALID_REQUEST
Malformed request body — or an idempotencyKey reused with different photo-test settings
401
UNAUTHORIZED
Missing or invalid API key
403
FORBIDDEN
Key lacks required scope
404
NOT_FOUND
Resource not found
409
CONFLICT
Without retryAfter: terminal — the idempotencyKey belongs to a photo test that was since cancelled (or can no longer be verified); send a fresh key. With retryAfter (older API instances during rollout): the key is still processing — retry it (a completed test simply replays its trialId)
409
IDEMPOTENCY_IN_PROGRESS
Another request with this idempotencyKey is still processing — retryable, with retryAfter seconds in the body and a Retry-After header. During the fenced rollout phase (WEB-10588) a first-use key on an upgraded instance returns this same response without the request being accepted; retries succeed via a remaining legacy instance or once the fence is lifted