Integrating the social network
You keep your own authentication. This API gives each of your users a private Known Distance profile inside your app - they set their name, bio and social links, upload an avatar and banner, see their activity. Server-to-server over HTTPS: authenticate every call with a key you generate below, sent as a Bearer token.
One profile per person, joined across sites by their verified email - always send emailVerified: true. Your embed shows each user their own private profile and activity; the full public profile lives in Known Distance, and the person takes control of it when they open a KD account with that email.
https://api-stream.knowndistance.com/api/v1Authorization: Bearer sk_live_........Your API keys
Generate a key to authenticate every call from your backend. The full secret is shown once - store it safely and keep it server-side (never in your app or browser). Revoke any key instantly.
Identity
Resolve a user
Server endpoint - use your sk_ key. Call it once per user, then use the profileId it returns for everything else.
Tell KD who your user is. Join key is the verified email: pass email + emailVerified:true so the same person is one profile across sites. Body: externalId, email, emailVerified, displayName, avatarUrl. Returns profileId (use this as :id below) and owned.
Profile
Read & edit the user's profile
Server endpoints - use your sk_ key. :id is the profileId from resolve. This is the private profile your app shows the user.
Read the profile to display it: displayName, avatarUrl, bannerUrl, bio, socialLinks.
Save edits. Body: displayName, bio, socialLinks (an object). Only sent fields change.
Upload the profile photo - multipart/form-data, field file (image, up to 8 MB). KD stores it and sets avatarUrl. You host nothing.
Upload the banner - same as above, sets bannerUrl.
Activity
Feed & read activity
Server endpoints - use your sk_ key. Feed the user's activity in, and read it back to show it.
Push a batch of your users' activity (an array, up to 500). Resolve the user first so it attaches to their profile. Each item: actor.externalId, verb, dedupeKey (required), plus optional title, url, objectType, objectId, visibility, occurredAt. Idempotent per dedupeKey.
Read the user's activity to display it in your app. Paged with ?limit & ?cursor.
Activity types
What you can share
Activity is free-form. The title you send is the line shown on the profile; verb and objectType are tags (grouping, icons), not a fixed list - send any kind. Use the vocabulary below so profiles stay consistent.
Recommended verbs
posted . published . commented . liked . followed . shared . reviewed . achieved . played . watched . listened . purchased . joined . checked_in
Recommended objectType
post . article . comment . review . badge . game . match . track . video . product . event . place
visibility: public shows on the person's public profile; private stays in the user's own view only.