Friends

Friend-request lifecycle — send, accept, reject, block, unblock; list accepted + pending.

Friendships are a single row with requester_id + addressee_id. Blocking preserves the row but switches status; unblocking deletes it.

Endpoints

Method	Path	Description
POST	`/client/friends/request`	Send a friend request.
POST	`/client/friends/:friendshipId/accept`	Accept a pending request (only the addressee can).
POST	`/client/friends/:friendshipId/reject`	Delete a pending request (only the addressee can).
POST	`/client/friends/:friendshipId/block`	Block — either participant can.
POST	`/client/friends/:friendshipId/unblock`	Delete a blocked row.
GET	`/client/friends`	Accepted + pending friendships with user detail.
GET	`/client/friends/pending`	Pending requests addressed to the caller.

POST /client/friends/request

Request (`SendFriendRequestInput`)

Field	Type	Required
`addressee_id`	uuid	yes

user_id is accepted in place of addressee_id.

Every friendship this router returns carries the SDKs' Friendship fields from the caller's side: user_id (the caller), friend_id (the other user) and state (the row's status).

Response 201

{
  "data": {
    "id": "…",
    "requester_id": "…",
    "addressee_id": "…",
    "status": "pending",
    "user_id": "…",
    "friend_id": "…",
    "state": "pending",
    "created_at": "…",
    "updated_at": "…"
  }
}

Errors

400 INVALID_REQUEST — can't friend yourself.
403 BLOCKED — existing row is blocked.
409 ALREADY_EXISTS — a friendship already exists in either direction.
500 CREATE_FAILED.

Try it:

POST/client/friends/request

client auth

curl -X POST 'https://api.amba.dev/v1/client/friends/request' \
  -H 'Content-Type: application/json' \
  -d '{
  "addressee_id": "<app_user_id>"
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/client/friends/request" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"addressee_id":"<app_user_id>"}'

POST /client/friends/:friendshipId/accept

Only succeeds if the caller is addressee_id and status is pending.

Errors

404 ACCEPT_FAILED — no pending request matched.
500 ACCEPT_FAILED.

Try it:

POST/client/friends/%7B%7BfriendshipId%7D%7D/accept

client auth

curl -X POST 'https://api.amba.dev/v1/client/friends/%7B%7BfriendshipId%7D%7D/accept'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/client/friends/{friendshipId}/accept" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/friends/:friendshipId/reject

Same eligibility as accept. Deletes the row.

Response 200

{ "data": { "deleted": true } }

Try it:

POST/client/friends/%7B%7BfriendshipId%7D%7D/reject

client auth

curl -X POST 'https://api.amba.dev/v1/client/friends/%7B%7BfriendshipId%7D%7D/reject'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/client/friends/{friendshipId}/reject" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/friends/:friendshipId/block

Either participant can block.

Errors

404 BLOCK_FAILED.

Try it:

POST/client/friends/%7B%7BfriendshipId%7D%7D/block

client auth

curl -X POST 'https://api.amba.dev/v1/client/friends/%7B%7BfriendshipId%7D%7D/block'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/client/friends/{friendshipId}/block" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/friends/:friendshipId/unblock

Deletes a blocked row owned by either participant.

Response 200

{ "data": { "deleted": true } }

Try it:

POST/client/friends/%7B%7BfriendshipId%7D%7D/unblock

client auth

curl -X POST 'https://api.amba.dev/v1/client/friends/%7B%7BfriendshipId%7D%7D/unblock'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/client/friends/{friendshipId}/unblock" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

The caller's accepted friendships, then pending requests in both directions, each newest first, with both user records attached. A pending row is incoming when addressee_id is the caller and outgoing when requester_id is. Blocked rows are left out: the table doesn't record which side blocked.

Query

Param	Description
`state`	`accepted` or `pending` lists that state alone. Omit it to list both.
`limit`	Rows per page, at most 1000 (the default).
`offset`	Rows to skip (default 0).

Response 200

{
  "data": [
    {
      "id": "…",
      "requester_id": "…",
      "addressee_id": "…",
      "status": "accepted",
      "requester": { "id": "…", "display_name": "…", "avatar_url": "…" },
      "addressee": { "id": "…", "display_name": "…", "avatar_url": "…" },
      "user_id": "…",
      "friend_id": "…",
      "state": "accepted",
      "created_at": "…",
      "updated_at": "…"
    }
  ]
}

Errors

400 INVALID_STATE — state is something other than accepted or pending.

Try it:

GET/client/friends

client auth

curl -X GET 'https://api.amba.dev/v1/client/friends'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/client/friends" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}"

GET /client/friends/pending

Pending requests where the caller is the addressee.

Response 200

{
  "data": [
    {
      "id": "…",
      "status": "pending",
      "requester": { "id": "…", "display_name": "…", "avatar_url": "…" }
    }
  ]
}

Try it:

GET/client/friends/pending

client auth

curl -X GET 'https://api.amba.dev/v1/client/friends/pending'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/client/friends/pending" \
  -H "X-Api-Key: ${CLIENT_API_KEY}" \
  -H "Authorization: Bearer ${SESSION_TOKEN}"

On this page