Artemis Users API: profiles, karma, and preferences

The Users API covers every operation related to Artemis accounts: reading the current user’s identity, fetching public profile data, creating new accounts, authenticating with the password grant, managing preferences, and maintaining friend relationships. Most endpoints under /api/v1/me require an OAuth2 bearer token with the appropriate scope.

GET /api/v1/me

Returns the identity of the currently authenticated user. Requires the identity OAuth2 scope.

Authorization

string

required

Bearer token obtained from the OAuth2 token endpoint.

curl -H "Authorization: Bearer <token>" \
     https://<your-artemis-instance>/api/v1/me

{
  "kind": "t2",
  "data": {
    "name": "alice",
    "id": "abc12",
    "link_karma": 1420,
    "comment_karma": 830,
    "inbox_count": 2,
    "is_mod": false,
    "gold": false,
    "email_verified": true,
    "has_subscribed": true,
    "over_18": false,
    "pref_hide_ads": false,
    "pref_no_profanity": true
  }
}

name

string

required

The account’s username.

string

required

The account’s base-36 ID.

link_karma

number

Total karma accumulated from link (post) submissions.

comment_karma

number

Total karma accumulated from comments.

inbox_count

number

Number of unread messages in the account’s inbox.

is_mod

boolean

Whether the user moderates at least one branch.

gold

boolean

Whether the account has an active gold membership.

email_verified

boolean

Whether the account’s email address has been verified.

has_subscribed

boolean

Whether the user has ever subscribed to a branch.

GET /user/:username/about.json

Returns the public profile information for any account. No authentication is required for public profiles.

username

string

required

The account username to look up.

curl https://<your-artemis-instance>/user/alice/about.json

{
  "kind": "t2",
  "data": {
    "name": "alice",
    "id": "abc12",
    "link_karma": 1420,
    "comment_karma": 830,
    "created_utc": 1609459200,
    "is_mod": false,
    "gold": false
  }
}

GET /user/:username/:where

Returns a paginated listing of a user’s content. Replace :where with one of the listing types below.

username

string

required

The account username.

where

string

required

The listing type. One of overview, submitted, comments, saved, hidden, upvoted, or downvoted.

after

string

Fullname of the item to use as the starting cursor for forward pagination.

before

string

Fullname of the item to use as the starting cursor for backward pagination.

limit

number

default:"25"

Maximum number of items to return. Accepted range is 1–100.

show

string

Pass given with upvoted or downvoted to expose votes on other users’ content (requires authentication and privacy settings to allow it).

The saved, hidden, upvoted, and downvoted listings are private and require the authenticated user to match :username, or require an admin session.

curl -H "Authorization: Bearer <token>" \
     "https://<your-artemis-instance>/user/alice/submitted?limit=10"

POST /api/register

Creates a new Artemis account.

user

string

required

The desired username. Must pass Artemis username validation rules.

passwd

string

required

The desired password.

passwd2

string

required

Password confirmation. Must match passwd.

string

Email address for the account (optional, but required for password recovery).

rem

boolean

default:"false"

When true, sets a long-lived session cookie rather than a session-scoped one.

Subscribe the email address to the site newsletter. Requires a valid email.

curl -X POST https://<your-artemis-instance>/api/register \
  -d "user=alice&passwd=secret1&passwd2=secret1&email=alice@example.com"

{
  "json": {
    "errors": [],
    "data": {
      "modhash": "abc123def456",
      "cookie": "session-cookie-value",
      "need_https": false
    }
  }
}

Registration is rate-limited by IP address. Repeated failures return a 429 response.

Logs into an existing account and returns a session cookie. For programmatic access, prefer the OAuth2 password grant via POST /api/v1/access_token.

user

string

required

The account username.

passwd

string

required

The account password.

rem

boolean

default:"false"

When true, issues a persistent cookie that survives browser restarts.

curl -X POST https://<your-artemis-instance>/api/login \
  -d "user=alice&passwd=secret1&rem=true"

{
  "json": {
    "errors": [],
    "data": {
      "modhash": "abc123def456",
      "cookie": "session-cookie-value",
      "need_https": false
    }
  }
}

POST /api/v1/access_token (password grant)

Obtains an OAuth2 access token using the password grant type. Only permitted for apps of type script.

Request
Response

grant_type

string

required

Must be password.

username

string

required

The account username.

password

string

required

The account password.

Authorization

string

required

HTTP Basic authentication using your OAuth2 client_id as the username and client_secret as the password.

curl -X POST https://<your-artemis-instance>/api/v1/access_token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=password&username=alice&password=secret1"

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "identity read submit vote"
}

access_token

string

The bearer token to include in the Authorization header on subsequent requests.

token_type

string

Always bearer.

expires_in

number

Seconds until the token expires.

scope

string

Space-separated list of granted OAuth2 scopes.

User preferences

GET /api/v1/me/prefs
PATCH /api/v1/me/prefs

Returns the preference settings of the currently authenticated user. Requires the identity scope.

fields

string

Comma-separated list of preference keys to return. When omitted, all preferences are returned.

curl -H "Authorization: Bearer <token>" \
     https://<your-artemis-instance>/api/v1/me/prefs

{
  "default_comment_sort": "confidence",
  "hide_ads": false,
  "label_nsfw": true,
  "lang": "en",
  "min_comment_score": -4,
  "min_link_score": -4,
  "newwindow": false,
  "no_profanity": true,
  "num_comments": 200,
  "numsites": 25,
  "over_18": false,
  "show_flair": true,
  "show_link_flair": true,
  "show_stylesheets": true,
  "threaded_messages": true
}

Updates one or more preferences for the current user. Requires the account scope. Send a JSON body with the preference keys you want to change.

curl -X PATCH https://<your-artemis-instance>/api/v1/me/prefs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"over_18": true, "no_profanity": false}'

{
  "default_comment_sort": "confidence",
  "hide_ads": false,
  "label_nsfw": true,
  "no_profanity": false,
  "over_18": true
}

Only include the fields you want to change. All other preferences retain their current values.

Friend relationships

The /api/v1/me/friends/:username endpoints manage the current user’s friend list. All three require the subscribe scope.

GET — get friend
PUT — add or update friend
DELETE — remove friend

Returns information about a specific friend, such as any note attached to the relationship.

username

string

required

The username of the friend to retrieve.

curl -H "Authorization: Bearer <token>" \
     https://<your-artemis-instance>/api/v1/me/friends/bob

{
  "name": "bob",
  "id": "def34",
  "date": 1680000000
}

Creates a new friend relationship or updates an existing one. This operation is idempotent.

username

string

required

The username to add as a friend.

name

string

Optional. If provided, must match the :username path parameter.

note

string

Optional personal note attached to the friend relationship. Maximum 300 characters. Requires a gold account.

curl -X PUT https://<your-artemis-instance>/api/v1/me/friends/bob \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "bob"}'

A 201 Created response is returned when the relationship is newly created; 200 OK when it already exists and is being updated.

Removes a friend relationship. Returns 204 No Content on success.

username

string

required

The username of the friend to remove.

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  https://<your-artemis-instance>/api/v1/me/friends/bob

GET /api/v1/me/karma

Returns a per-branch breakdown of the authenticated user’s karma. Requires the mybranches scope.

curl -H "Authorization: Bearer <token>" \
     https://<your-artemis-instance>/api/v1/me/karma

{
  "kind": "KarmaList",
  "data": [
    {
      "sr": "programming",
      "link_karma": 840,
      "comment_karma": 120
    },
    {
      "sr": "science",
      "link_karma": 580,
      "comment_karma": 710
    }
  ]
}

Authentication

Endpoints

Developer Guide

Artemis Users API: profiles, karma, and preferences

GET /api/v1/me

GET /user/:username/about.json

GET /user/:username/:where

POST /api/register

POST /api/v1/access_token (password grant)

User preferences

Friend relationships

GET /api/v1/me/karma

Build docs developers (and LLMs) love

Authentication

Endpoints

Developer Guide

Documentation Index

​GET /api/v1/me

​GET /user/:username/about.json

​GET /user/:username/:where

​POST /api/register

​POST /api/login

​POST /api/v1/access_token (password grant)

​User preferences

​Friend relationships

​GET /api/v1/me/karma

Build docs developers (and LLMs) love

GET /api/v1/me

GET /user/:username/about.json

GET /user/:username/:where

POST /api/register

POST /api/login

POST /api/v1/access_token (password grant)

User preferences

Friend relationships

GET /api/v1/me/karma