Getting started

Base URLs

All endpoints are prefixed with /v1.

Versioning

The API is versioned through the URL path (/v1/...). Breaking changes ship as a new major version; the previous version stays available until it is deprecated.

Your first request

Almost every endpoint requires an authenticated session. The quickest way to verify the API is reachable is the login endpoint, which returns the Google sign-in URL:

curl -X POST https://api.peridot.id/v1/auth/login

{ "url": "https://api.peridot.id/v1/auth/google" }

Open url in a browser and sign in with Google. You are redirected back with the session cookies set. From then on, use a cookie jar for all requests:

# Save the session cookies (browser already set them; for non-browser clients use -c)
curl -b cookies.txt https://api.peridot.id/v1/identity/me

{
  "id": "2f4b1c1e-8a6f-4d7a-9c3d-1a2b3c4d5e6f",
  "createdAt": "2026-08-03T13:30:00.000Z"
}

Read the reference

Every endpoint, schema, and example is documented in the API reference.