Skip to main content
POST
/
users
/
@me
/
relationships
/
{username}
Create relationship
curl --request POST \
  --url https://api.example.com/users/@me/relationships/{username} \
  --header 'Authorization: <authorization>'
{
  "400": {},
  "401": {},
  "relationship": {
    "requester": {
      "id": "<string>",
      "username": "<string>",
      "status": 123
    },
    "requestee": {
      "id": "<string>",
      "username": "<string>",
      "status": 123
    },
    "status": "<string>"
  }
}
Creates a new friend request to another user or accepts an incoming friend request from that user.

​
Path parameters

​
username
string
required
The username of the user to send a friend request to or accept a request from

​
Authorization

​
Authorization
string
required
JWT token for authentication. Must be provided in the format: Bearer <token>

​
Response

Returns the created or accepted relationship object with a 201 Created status code.
​
relationship
SafeRelationship
The created or accepted relationship

​
Error codes

​
400
Bad Request
The request is invalid. This can occur for several reasons:InvalidFriendRequestException
{
  "message": "User with username \"username\" doesn't exist."
}
The user you’re trying to friend doesn’t exist.SelfFriendException
{
  "message": "You can't friend yourself. Try making friends :)"
}
You attempted to send a friend request to yourself.ExistingRelationshipException
{
  "message": "You are already friends with \"username\""
}
An incoming or accepted relationship already exists with this user.OutgoingRequestAlreadyExistsException
{
  "message": "You can't create another outgoing request for \"username\""
}
You already have a pending outgoing friend request to this user.
​
401
Unauthorized
Authorization token was not provided or is invalid.
{
  "message": "Unauthorized"
}

​
Example request

curl -X POST "http://localhost:8080/users/@me/relationships/alice" \
  -H "Authorization: Bearer your-jwt-token"

​
Example response

​
Sending a new friend request

{
  "requester": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "username": "bob",
    "status": 1
  },
  "requestee": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "username": "alice",
    "status": 2
  },
  "status": "PENDING"
}

​
Accepting an incoming friend request

{
  "requester": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "username": "alice",
    "status": 2
  },
  "requestee": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "username": "bob",
    "status": 1
  },
  "status": "ACCEPTED"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us