Skip to content
CAVS Node

Identity & discovery

Routes directly under /api/v1 that aren’t scoped to an organization or a repository. All require authentication.

Terminal window
export API=https://cavsnode.com/api/v1
export H="Authorization: Bearer $CAVS_TOKEN"

Current user

Section titled “Current user”

GET /users/me

Section titled “GET /users/me”

The authenticated identity plus every organization it can see. This is the first call to make when debugging a permission problem.

Terminal window
curl -sS "$API/users/me" -H "$H"
{
  "user": {
    "id": "77bc…",
    "email": "[email protected]",
    "display_name": "You",
    "avatar_url": "https://…",
    "status": "ACTIVE",
    "created_at": "2026-06-01T09:00:00Z"
  },
  "organizations": [
    { "id": "0a11…", "name": "Acme AI", "slug": "acme-ai", "role": "OWNER", "plan_id": "team" }
  ]
}

For a cavs_repo_ or cavs_ci_ token there is no user behind the credential, so user may be absent — the token’s organization and scopes are what matter.

PATCH /users/me

Section titled “PATCH /users/me”

Update your own profile (display name, avatar).

Terminal window
curl -sS -X PATCH "$API/users/me" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"display_name": "Your Name"}'

POST /auth/session

Section titled “POST /auth/session”

Idempotently sync the user record from the Firebase identity. The dashboard calls this after sign-in; you rarely need it directly.

Terminal window
curl -sS -X POST "$API/auth/session" -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
Section titled “Search”
Section titled “GET /search”

Searches repositories, files, commits and releases, scoped to the organizations the caller can see.

Terminal window
curl -sS "$API/search?q=resnet" -H "$H"
curl -sS "$API/search?q=checkpoint&type=files&ext=safetensors" -H "$H"
curl -sS "$API/search?q=fix+dataloader&type=commits&repo=$REPO" -H "$H"
curl -sS "$API/search?q=weights&type=files&min_size=1000000000" -H "$H"
Parameter Meaning
q The query. Required.
type repos, files, commits, releases. Omit for all.
org Restrict to one organization
repo Restrict to one repository (UUID)
ext File extension filter — files only
min_size, max_size Byte-size bounds — files only

Commit-message search uses a text index. File and commit results come from the Git index, so a repository that has never been indexed won’t appear in those categories.

From the CLI: cav search "resnet".

Notifications

Section titled “Notifications”

GET /notifications

Section titled “GET /notifications”

Your in-app notifications: invitations, quota warnings, storage-connection health, webhook auto-disable, billing events.

Terminal window
curl -sS "$API/notifications" -H "$H"

POST /notifications/{id}/read

Section titled “POST /notifications/{id}/read”

Mark one as read.

Terminal window
curl -sS -X POST "$API/notifications/$ID/read" -H "$H"

Invitations

Section titled “Invitations”

Accepting works from either side: the emailed link (which carries a token) or the in-app notification (which needs no token, and matches on your email server-side).

POST /invitations/accept

Section titled “POST /invitations/accept”

Accept using the token from an invitation link.

Terminal window
curl -sS -X POST "$API/invitations/accept" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"token": "<from the link>"}'

GET /users/me/invitations

Section titled “GET /users/me/invitations”

Invitations pending for your email address — what the notifications bell renders.

Terminal window
curl -sS "$API/users/me/invitations" -H "$H"

POST /invitations/{invID}/accept

Section titled “POST /invitations/{invID}/accept”

Accept by id, without a token. The server enforces that the signed-in email matches the invitation.

Terminal window
curl -sS -X POST "$API/invitations/$INV/accept" -H "$H"

For a repository invitation the response includes repository_id, so a UI can redirect straight to it.

GET /users/me/shared-repositories

Section titled “GET /users/me/shared-repositories”

Repositories shared with you as an external collaborator.

Terminal window
curl -sS "$API/users/me/shared-repositories" -H "$H"

Public endpoints

Section titled “Public endpoints”

No credential needed.

GET /api/v1/plans

Section titled “GET /api/v1/plans”

The plan catalogue with limits, prices and feature flags. This is what the pricing page reads.

Terminal window
curl -sS https://cavsnode.com/api/v1/plans | jq '.plans[] | {id, name, price_cents_monthly}'

GET /readyz

Section titled “GET /readyz”

Readiness, including a database ping. Use this for external monitoring.

Terminal window
curl -sS https://cavsnode.com/readyz     # → ready

Next

Section titled “Next”