REST API Overview

Audience Note

The pages in this group are different from the rest of this site. They're written for developers integrating Remy into their own scripts, automations, or applications. If you're a regular user looking to manage your contact book, the Contacts, Google Sync, and Notes pages cover everything you need without the API.

Overview

Every CRUD resource in Remy's user-facing app is also exposed as a versioned REST API for external use. Today the API exposes:

• Contacts — list, get, create, update, delete. See Contacts API.
• Notes — list per contact, create, update, delete. See Notes API.
• Data export — full account export in JSON or CSV. See Export API.

Other surfaces (tags, intros, billing, integrations) aren't exposed as standalone endpoints today. Tags and "introduced by" links are managed as fields on the contact resource — you can read and set them through PATCH /api/v1/contacts/:id.

Base URL

https://app.remy.com/api/v1

All endpoints live under /api/v1. Future versions will use a different prefix; v1 will continue to work.

Authentication

Every request requires an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer rmy_<your-key>

API keys are scoped to your account and inherit your data's access boundaries — you can only read and write your own data through them. Create and manage keys in Settings → API Keys, or read API Keys for the full lifecycle.

A missing or invalid key returns:

{ "error": "Missing Authorization header" }

or

{ "error": "Invalid, expired, or revoked API key" }

both with status 401.

Response Format

Every successful response is JSON with a small set of conventions.

Single resource

{ "data": { ... } }

List

{ "data": [ ... ], "total": 42 }

total is the count before pagination is applied — useful for displaying "showing 1–50 of 200" in your own UI.

Errors

{ "error": "Human-readable message" }

For validation errors, a details field carries the field-level breakdown produced by the underlying validator:

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "givenName": ["Too long"]
    },
    "formErrors": []
  }
}

Status Codes

Pagination

List endpoints accept limit and offset query parameters.

• limit — number of results to return. Default 50, max 100.
• offset — how many results to skip from the start. Default 0.

The response includes total, the unpaginated count, so you can compute pages and current page client-side.

Idempotency

GET, PATCH, and DELETE are naturally idempotent — repeating the same request produces the same result.

POST is not idempotent. If you retry a POST /api/v1/contacts after a network error, you may end up with two contacts. There is no idempotency key today.

Rate Limits

The API has soft rate limits to keep abusive scripts from degrading service. Sustained calls under a few requests per second per API key won't run into them. If you do, requests will receive a 429 with a brief retry-after window.

Audit Trail

Every mutation made through the REST API is recorded in the Activity Log with authMethod: "api_key" so you can distinguish API-driven changes from dashboard-driven ones. The IP and user-agent of the calling client are also captured.

Frequently Asked Questions

Is there a Remy SDK?

Not today. The API is small and stable enough that a few fetch calls in any language work fine. Community SDKs are welcome.

Can I use the API without a paid plan?

Yes. API access is on every plan including free, scoped to your data.

Are outbound event notifications available?

Not today. The roadmap includes outbound HTTP callbacks for sync events; if you need a polling-based equivalent, the Activity Log carries everything that would otherwise be pushed to your own server.

What's the deprecation policy?

Breaking changes ship under a new version prefix (/api/v2). Within /api/v1, additions are non-breaking; removals or renames go through a published deprecation period.

How do I report a bug or request a missing endpoint?

Reach out via your in-app help link. Resource-specific gaps (e.g., tags as a standalone endpoint) are tracked but currently low priority — most use cases are covered by the contact and note endpoints.