field schemas and examples

settings patch shape

PATCH /me/settings accepts {target_id?,patch}. without target_id, patch may contain only account fields. with target_id, it may contain only instance fields. both GET and PATCH return {target_id,values,revision}; GET returns the full permitted projection, PATCH only changed values. omission leaves a setting unchanged. account fields are shareOnline, shareTyping, allowFriendRequests, allowGroupDMs, quietEnabled, quietStart, quietEnd, quietDays, quietTimezone, quietAllowCalls, pausedUntil, theme, emojiSkinTone and doubleClickEmoji. instance fields are timezone, push, inApp, ringtone, messages, reactions, friendRequests, calls, preview, audioMode, microphone, camera, output, joinMuted, callSounds, gameSounds, soundVolume, followSystemTheme, textSize, spacing, motion, autoplay, loadMedia, subtleDrawings, enterSends and showMyCameraPreview. changing a privacy preference does not add another bot grant.

1
2
3
4
5
6
7
8{
  "target_id": "settings_target_example",
  "patch": {
    "soundVolume": 60,
    "audioMode": "studio",
    "joinMuted": true
  }
}

setting values

boolean controls accept true/false only. quietStart/quietEnd use HH:mm; quietDays contains unique integers 0–6; scheduled quiet hours use the account’s quietTimezone; pausedUntil is null or an RFC 3339 timestamp at most 30 days ahead. timezone is an IANA name. textSize is an integer 12–22 and soundVolume 0–100. preview is full|sender|hidden; audioMode noise-cancelling|studio; spacing comfortable|compact; motion system|reduce|full; enterSends auto|send|newline. microphone/camera/output are known opaque device-choice IDs or the empty default. theme, emojiSkinTone and announcement-pack IDs come from limits/catalogues; doubleClickEmoji is one supported emoji grapheme. server-only account security fields and unlisted settings are invalid_request. profile artwork, library actions and blocks remain separate endpoints.

profile patch shape

the v1 profile API maps about to the app’s bio field and maps palette IDs to existing stored color values. palette IDs are red, orange, yellow, lime, green, teal, blue, purple, pink and gray; null uses the theme default. profile_art and nameplate_art replace their respective complete validated artwork values, guarded by If-Match. profile reads include normal visible fields only and never reveal private account or testing administration data.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "display_name": "Avery",
  "about": "making things",
  "pronouns": "they/them",
  "avatar_asset_id": "asset_avatar",
  "banner_asset_id": null,
  "background_gradient": {
    "top": "#ccd9cc",
    "bottom": "#e8dfce"
  },
  "nameplate_name_color": "blue",
  "nameplate_background_color": null,
  "online_indicator_color": "green",
  "announcement_pack": ""
}

profile artwork shape

artwork is {version:2,strokes,items}. stroke fields are id,anchor_seq,canvas_width,tool,color,size,points,draw_order and optional erasures. artwork stroke IDs and item IDs are UUIDs, unlike opaque resource IDs elsewhere. anchor_seq must be zero. size is 1–24 reference-canvas pixels; point coordinates are normalized by canvas width. item fields are id,kind,value,x,y,width,height,rotation,order, with positions and sizes in canvas pixels. kind is emoji or sticker; nameplate items allow only emoji. nameplate stroke colors use canonical six-digit palette values or opaque #rrggbbff for fixed sampled colors. erasures contain {id,size,points}; all counts, bounds and retained asset ownership use the existing ProfileArt v2 validator.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27{
  "nameplate_art": {
    "version": 2,
    "strokes": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "anchor_seq": 0,
        "canvas_width": 280,
        "tool": "pen",
        "color": "#3e5bb0",
        "size": 3,
        "points": [
          [
            0.1,
            0.1
          ],
          [
            0.2,
            0.15
          ]
        ],
        "draw_order": 1
      }
    ],
    "items": []
  }
}

limits response

GET /limits returns {api_version,catalogue_version,limits,fields,quotas}. limits contains the named numeric buckets from the limits chapter; fields contains allowed enums and min/max bounds for settings, profile, artwork, media, group capacity and text; quotas contains only the current installer/application’s relevant counters. it is discovery metadata, not authority to perform an action. the example below shows selected fields from the complete response. quota entries appear only for granted capabilities; cancelled and failed uploads still consume the daily byte budget.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48{
  "api_version": 1,
  "catalogue_version": 1,
  "limits": {
    "rest_application": {
      "capacity": 100,
      "refill": 50,
      "period_ms": 1000
    },
    "uploads": {
      "concurrent": 3,
      "daily_bytes": 524288000,
      "part_bytes": 10485760,
      "lifetime_ms": 900000
    }
  },
  "fields": {
    "profile": {
      "display_name": {
        "type": "string",
        "x-weighted-max-length": 20,
        "x-weighted-min-length": 1,
        "description": "length uses sometimes weighted textLength; UTF-16 maxLength is not equivalent."
      },
      "about": {
        "type": "string",
        "x-weighted-max-length": 200,
        "x-weighted-min-length": 0,
        "description": "length uses sometimes weighted textLength; UTF-16 maxLength is not equivalent.",
        "x-max-lines": 6
      }
    },
    "instance_settings": {
      "textSize": {
        "type": "integer",
        "minimum": 12,
        "maximum": 22
      }
    }
  },
  "quotas": {
    "user_stickers": {
      "used": 3,
      "limit": 25,
      "remaining": 22
    }
  }
}

machine-readable schemas

download the OpenAPI 3.1 document for REST request and response schemas, and the gateway JSON Schema for client frames, server frames and event payloads. both reuse the field bounds returned by /limits and are checked against actual Worker requests and responses. media signaling uses the REST SessionDescription, Track and Negotiation schemas; WebRTC transports the media. unknown request fields and unsupported actors are rejected.

additional resource routes

these routes complement the detailed resource chapters. use the OpenAPI document for complete response shapes, headers and field constraints.

scroll the table horizontally to see all columns.

dashboard and app integration routes

these additional routes use human authentication and the app’s CSRF protection. bot tokens cannot use them. dashboard changes require the application If-Match revision; image reads apply profile visibility rules. the normal dashboard, installation page and message bar call these routes for you.

scroll the table horizontally to see all columns.