Users

All endpoints use the base URL /v1. Authenticated endpoints require a valid Bearer token in the Authorization header.

---

Profiles

Get Current Profile

GET /v1/profiles/me

Returns the full profile of the authenticated user, including wallet and installed apps.

Authentication: Required

Response 200 OK:

{
  "profile": {
    "id": "uuid",
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "janedoe",
    "avatar_url": "https://cdn.example.com/avatars/janedoe.jpg",
    "caption": "Building cool things.",
    "verified": true,
    "created_at": "2025-01-15T08:30:00.000Z",
    "updated_at": "2025-06-01T12:00:00.000Z"
  },
  "wallet": {
    "id": "uuid",
    "balance": 1500,
    "currency": "USD"
  },
  "installed_apps": [
    {
      "app_id": "uuid",
      "is_active": true
    }
  ]
}

Note

The wallet field is null if the user has not set up a wallet. The installed_apps array may be empty.

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.
404 Not Found	No profile exists for the authenticated user.

---

Update Profile

PATCH /v1/profiles/me

Updates the authenticated user’s profile. Only whitelisted fields are accepted; any other fields in the request body are ignored.

Authentication: Required

Request Body:

Field	Type	Required	Description
first_name	string	No	User’s first name
last_name	string	No	User’s last name
username	string	No	Unique username
avatar_url	string	No	URL to the avatar image
caption	string	No	Short profile bio/caption

Caution

Only these five fields are updatable. All other fields are silently stripped from the request. At least one valid field must be provided.

Request Example:

{
  "first_name": "Jane",
  "caption": "New caption here."
}

Response 200 OK:

{
  "profile": {
    "id": "uuid",
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "janedoe",
    "avatar_url": "https://cdn.example.com/avatars/janedoe.jpg",
    "caption": "New caption here.",
    "verified": true,
    "created_at": "2025-01-15T08:30:00.000Z",
    "updated_at": "2025-06-02T10:00:00.000Z"
  }
}

Errors:

Status	Description
400 Bad Request	No valid fields provided, or a database error occurred.
401 Unauthorized	Missing or invalid Bearer token.

---

Delete Account

DELETE /v1/profiles/me

Permanently deletes the authenticated user’s account. This action is irreversible.

Authentication: Required

Request Body (optional):

Field	Type	Required	Description
reason	string	No	Reason for deleting the account
feedback	string	No	Additional feedback about the experience

Tip

If reason or feedback is provided, it is saved to the account_deletion_feedback table before the account is removed from Supabase Auth.

Side Effects:

1. A row is inserted into the account_deletion_feedback table (if reason/feedback provided).
2. The user is deleted from Supabase Auth, which cascades to all related data.

Response 200 OK:

{
  "message": "Account deleted"
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Get Public Profile

GET /v1/profiles/{username}

Returns the public profile for a given username. No authentication required.

Authentication: None

Path Parameters:

Parameter	Type	Required	Description
username	string	Yes	The user’s unique username

Response 200 OK:

{
  "profile": {
    "id": "uuid",
    "username": "janedoe",
    "first_name": "Jane",
    "last_name": "Doe",
    "avatar_url": "https://cdn.example.com/avatars/janedoe.jpg",
    "caption": "Building cool things.",
    "verified": true,
    "created_at": "2025-01-15T08:30:00.000Z"
  },
  "followers_count": 128,
  "following_count": 64
}

Errors:

Status	Description
404 Not Found	No profile found for the given username.

---

Get User’s Posts

GET /v1/profiles/{username}/posts

Returns a cursor-paginated list of a user’s published posts. No authentication required.

Authentication: None

Path Parameters:

Parameter	Type	Required	Description
username	string	Yes	The user’s unique username

Query Parameters:

Parameter	Type	Default	Description
cursor	string	—	Cursor value (created_at) from a previous response for pagination.
limit	integer	20	Number of posts to return. Maximum 50.

Note

Pagination is cursor-based using the created_at timestamp. Only posts with a published status are returned. To fetch the next page, pass the next_cursor value from the previous response.

Response 200 OK:

{
  "posts": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "created_at": "2025-06-01T12:00:00.000Z",
      "status": "published",
      "profiles": {
        "id": "uuid",
        "username": "janedoe",
        "first_name": "Jane",
        "last_name": "Doe",
        "avatar_url": "https://cdn.example.com/avatars/janedoe.jpg"
      }
    }
  ],
  "next_cursor": "2025-05-28T09:15:00.000Z"
}

When there are no more results, next_cursor is null.

---

Get Followers

GET /v1/profiles/{username}/followers

Returns a cursor-paginated list of users who follow the specified user. Only relationships with status='following' are included.

Authentication: None

Path Parameters:

Parameter	Type	Required	Description
username	string	Yes	The user’s unique username

Query Parameters:

Parameter	Type	Default	Description
cursor	string	—	Cursor value from a previous response for pagination.
limit	integer	20	Number of followers to return. Maximum 50.

Response 200 OK:

{
  "followers": [
    {
      "follower_id": "uuid",
      "created_at": "2025-03-10T14:30:00.000Z",
      "profiles": {
        "id": "uuid",
        "username": "alexsmith",
        "first_name": "Alex",
        "last_name": "Smith",
        "avatar_url": "https://cdn.example.com/avatars/alexsmith.jpg"
      }
    }
  ],
  "next_cursor": "2025-02-20T08:00:00.000Z"
}

When there are no more results, next_cursor is null.

---

Get Following

GET /v1/profiles/{username}/following

Returns a cursor-paginated list of users the specified user is following. Only relationships with status='following' are included.

Authentication: None

Path Parameters:

Parameter	Type	Required	Description
username	string	Yes	The user’s unique username

Query Parameters:

Parameter	Type	Default	Description
cursor	string	—	Cursor value from a previous response for pagination.
limit	integer	20	Number of results to return. Maximum 50.

Response 200 OK:

{
  "following": [
    {
      "following_id": "uuid",
      "created_at": "2025-04-05T10:00:00.000Z",
      "profiles": {
        "id": "uuid",
        "username": "mchen",
        "first_name": "Morgan",
        "last_name": "Chen",
        "avatar_url": "https://cdn.example.com/avatars/mchen.jpg"
      }
    }
  ],
  "next_cursor": "2025-03-15T06:45:00.000Z"
}

When there are no more results, next_cursor is null.

---

Settings

All settings endpoints require authentication and use an upsert strategy — if no row exists for the authenticated user, one is created automatically.

Get Privacy Settings

GET /v1/settings/privacy

Returns the authenticated user’s privacy preferences.

Authentication: Required

Response 200 OK:

{
  "privacy": {
    "user_id": "uuid",
    "follower_approval": false,
    "show_online_status": true,
    "show_activity_status": true
  }
}

---

Update Privacy Settings

PATCH /v1/settings/privacy

Updates privacy preferences. Uses upsert on user_id.

Authentication: Required

Request Body:

Field	Type	Required	Description
follower_approval	boolean	No	Require approval for new followers.
show_online_status	boolean	No	Show online status to other users.
show_activity_status	boolean	No	Show activity status to other users.

Request Example:

{
  "follower_approval": true,
  "show_online_status": false
}

Response 200 OK:

{
  "privacy": {
    "user_id": "uuid",
    "follower_approval": true,
    "show_online_status": false,
    "show_activity_status": true
  }
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Get Security Settings

GET /v1/settings/security

Returns the authenticated user’s security preferences.

Authentication: Required

Response 200 OK:

{
  "security": {
    "user_id": "uuid",
    "two_factor_enabled": false
  }
}

---

Update Security Settings

PATCH /v1/settings/security

Updates security preferences. Uses upsert on user_id.

Authentication: Required

Request Body:

Field	Type	Required	Description
two_factor_enabled	boolean	No	Enable or disable 2FA.

Request Example:

{
  "two_factor_enabled": true
}

Response 200 OK:

{
  "security": {
    "user_id": "uuid",
    "two_factor_enabled": true
  }
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Get Notification Preferences

GET /v1/settings/notifications

Returns the authenticated user’s notification preferences.

Authentication: Required

Response 200 OK:

{
  "notifications": {
    "user_id": "uuid",
    "push_enabled": true,
    "email_enabled": true,
    "marketing_emails": false
  }
}

Note

The notification preferences schema is dynamic. The response may include additional fields beyond the examples shown here as new notification types are added.

---

Update Notification Preferences

PATCH /v1/settings/notifications

Updates notification preferences. Uses upsert on user_id. The schema is flexible to accommodate new notification types.

Authentication: Required

Request Body:

Field	Type	Required	Description
any	boolean	No	Dynamic key-value pairs for notification preferences.

Request Example:

{
  "push_enabled": false,
  "email_enabled": true
}

Response 200 OK:

{
  "notifications": {
    "user_id": "uuid",
    "push_enabled": false,
    "email_enabled": true,
    "marketing_emails": false
  }
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Get Account Settings

GET /v1/settings/account

Returns account-level information fetched from the Supabase Auth system.

Authentication: Required

Response 200 OK:

{
  "account": {
    "email": "jane@example.com",
    "phone": "+1234567890",
    "created_at": "2025-01-15T08:30:00.000Z"
  }
}

Note

The phone field may be null if no phone number is associated with the account.

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Update Account Settings

PATCH /v1/settings/account

Updates account-level settings via the Supabase Auth Admin API.

Authentication: Required

Request Body:

Field	Type	Required	Description
email	string	No	New email address for the account.
phone	string	No	New phone number for the account.

Request Example:

{
  "email": "newemail@example.com"
}

Response 200 OK:

{
  "account": {
    "email": "newemail@example.com",
    "phone": "+1234567890",
    "created_at": "2025-01-15T08:30:00.000Z"
  }
}

Errors:

Status	Description
400 Bad Request	Invalid email or phone format.
401 Unauthorized	Missing or invalid Bearer token.

---

Onboarding

Get Onboarding Status

GET /v1/onboarding

Returns the current onboarding state for the authenticated user.

Authentication: Required

Response 200 OK (onboarding in progress or completed):

{
  "onboarding": {
    "user_id": "uuid",
    "completed": true,
    "completed_at": "2025-01-16T09:00:00.000Z",
    "updated_at": "2025-01-16T09:00:00.000Z",
    "profile_setup": {
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "interests": {
      "categories": ["technology", "design"]
    }
  }
}

Response 200 OK (no onboarding record exists):

{
  "onboarding": {
    "completed": false
  }
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Update Onboarding Step

POST /v1/onboarding

Saves progress for a specific onboarding step. Uses upsert on the user’s onboarding record and dynamically sets the step name as a field on the record.

Authentication: Required

Request Body:

Field	Type	Required	Description
step	string	Yes	The name of the onboarding step (used as the field key).
data	object	Yes	The data to store for this step.

Request Example:

{
  "step": "profile_setup",
  "data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "avatar_url": "https://cdn.example.com/avatars/janedoe.jpg"
  }
}

This creates or updates the onboarding record, setting the profile_setup field to the provided data object:

Response 200 OK:

{
  "onboarding": {
    "user_id": "uuid",
    "completed": false,
    "completed_at": null,
    "updated_at": "2025-01-15T10:30:00.000Z",
    "profile_setup": {
      "first_name": "Jane",
      "last_name": "Doe",
      "avatar_url": "https://cdn.example.com/avatars/janedoe.jpg"
    }
  }
}

Errors:

Status	Description
400 Bad Request	Missing step or data field in request body.
401 Unauthorized	Missing or invalid Bearer token.

---

Complete Onboarding

POST /v1/onboarding/complete

Marks the onboarding flow as completed for the authenticated user. Sets completed to true and completed_at to the current timestamp.

Authentication: Required

Request Body: None

Response 200 OK:

{
  "onboarding": {
    "user_id": "uuid",
    "completed": true,
    "completed_at": "2025-01-16T09:00:00.000Z",
    "updated_at": "2025-01-16T09:00:00.000Z",
    "profile_setup": {
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "interests": {
      "categories": ["technology", "design"]
    }
  }
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.