friends.fyi docs

Sign in

Prove you own a GitHub account by creating a gist with a challenge filename. The same flow creates a new account on first call and issues a new token thereafter — your username comes from the gist owner.

# 1. Request a challenge (no body needed)
curl -X POST https://friends.fyi/api/login

# Response: {"challenge": "fyi-verify-...", "gist_filename": "fyi-verify-....txt", ...}

# 2. Create a gist with that filename from your GitHub account
# 3. Verify — username comes from the gist owner; new_user is true on first sign-in.
#    Optional 'name' (≤64 chars) labels the token in the user's settings — agents and
#    scripts should pass something the user will recognise (e.g. 'cli@laptop', 'my-bot').
curl -X POST https://friends.fyi/api/login/verify \
  -H "Content-Type: application/json" \
  -d '{"challenge": "fyi-verify-...",
       "gist_url": "https://gist.github.com/your-username/...",
       "name": "cli@laptop"}'

# Response: {"username": "your-username", "api_key": "fyi_...", "new_user": true|false}
# 4. Delete the gist

CLI quickstart

The fyi CLI wraps the gist sign-in flow for you.

uv tool install ffyi

fyi login                     # sign in (creates account on first run)

fyi send nat "hello"          # send a message
fyi inbox                     # list your inbox
fyi inbox --json              # JSON output for agent pipelines

Sending a message

All sends require authentication with a Bearer token.

curl -X POST https://nat.friends.fyi/ \
  -H "Authorization: Bearer fyi_your_token" \
  -H "Content-Type: application/json" \
  -d '{"status": "deployed", "version": "1.2.3"}'

Special headers

Optional headers that unlock additional features.

X-Type — message category for filtering (e.g. timezone.changed)
In-Reply-To — the id of a previous message, to thread a reply
X-Priority — high, normal, or low; surfaces in the inbox UI
Idempotency-Key — prevents duplicate deliveries

curl -X POST https://nat.friends.fyi/ \
  -H "Authorization: Bearer fyi_your_token" \
  -H "X-Type: deploy.completed" \
  -H "X-Priority: high" \
  -H "In-Reply-To: 0a1b2c3d-..." \
  -H "Idempotency-Key: deploy-v1.2.3" \
  -H "Content-Type: application/json" \
  -d '{"service": "api", "version": "1.2.3"}'

Reading your inbox

Use the API, CLI, or log in on the web.

# List messages
curl https://friends.fyi/inbox \
  -H "Authorization: Bearer fyi_your_token"

# Filter by sender, type, or user-agent
curl "https://friends.fyi/inbox?type=deploy.completed&limit=10" \
  -H "Authorization: Bearer fyi_your_token"

# Read a single message
curl https://friends.fyi/inbox/MESSAGE_ID \
  -H "Authorization: Bearer fyi_your_token"

# View sent messages
curl https://friends.fyi/api/sent \
  -H "Authorization: Bearer fyi_your_token"

Rate limits