fep

FEP-65ca: Common Client Configuration

Summary

Third-party fediverse clients routinely need to know what a server will accept before a user presses “post”: how many attachments, which file types and sizes, how long a post, bio or alt text can be, whether usernames can change, and where a user goes to reset their password. Today this information is software-specific, undocumented, hardcoded into clients, or discovered only after a request is rejected.

This proposal defines a discovery endpoint at /.well-known/activitypub-client-config that links to a JSON document describing a server’s media upload limits, composer limits, account limits, and human-facing account pages, in a software-neutral format. Unauthenticated requests receive the limits of a default account; servers whose limits depend on the account MAY return the effective limits of the signed-in account when the request is authenticated.

Motivation

Clients that support more than one kind of fediverse server currently face a bad set of options:

  1. Hardcode limits per server software and version, which breaks whenever an administrator changes a setting.
  2. Rely on a software-specific instance API, whose shape reflects one platform’s feature set and cannot express things like photo albums, video duration caps, mixed media rules or username rules.
  3. Let the user compose a post, upload a file or edit a profile, then surface a rejection error after the work is done.

NodeInfo describes server metadata and usage statistics, and is explicitly not designed for this. This FEP fills that gap with a small, versioned, extensible document focused on the limits a client needs to build a correct composer, uploader and profile editor.

Scope

Although the endpoint name references ActivityPub, this FEP is not tied to the ActivityPub client-to-server protocol. It describes the server a client is talking to, and is equally useful to clients that use ActivityPub C2S, a Mastodon-compatible API, or a software-specific API.

Requirements Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

Terminology

Discovery

Discovery document

A server implementing this FEP MUST respond to:

GET /.well-known/activitypub-client-config

with HTTP status 200 and a Content-Type of application/json. The body is a JSON object with a single REQUIRED member, links, an array of link objects:

{
  "links": [
    {
      "rel": "https://w3id.org/fep/65ca/1.0",
      "href": "https://example.social/api/client-config/1.0"
    }
  ]
}

Each link object has two REQUIRED members:

Member Type Description
rel string A URI identifying the configuration document version. For version 1.x of this FEP the value is https://w3id.org/fep/65ca/1.0. The URI is an identifier and need not be dereferenceable.
href string The absolute https URL of the configuration document.

Requirements:

Configuration document

Fetching the href MUST return HTTP status 200, a Content-Type of application/json, and a body conforming to Configuration Document.

HTTP requirements

These requirements apply to both the discovery document and the configuration document.

Account-scoped configuration

On many servers, limits depend on the account: its role, plan, trust level or age. A newly registered account might not be allowed to post at all, while authors and editors have generous upload limits. A server MAY return an account-scoped document when the request for the configuration document is authenticated, so that a client gets the limits of the account it is signed in with.

Support is OPTIONAL. A server that does not support it returns the default document to every requester.

Server requirements

A server that supports account-scoped documents:

Access-Control-Allow-Origin: * remains valid for authenticated requests because a bearer token is sent as an ordinary request header, not as a browser credential. Browser clients MUST NOT set credentials: "include" on this request.

Client behavior

Configuration Document

General rules

Versioning

The version member is REQUIRED and has the form "1.<minor>". Minor versions only add OPTIONAL members. Clients MUST ignore members they do not recognize, at every level of the document.

Absent, null and zero

null MUST NOT be used on non-limit fields.

Units

All limit fields are integers unless stated otherwise. Sizes are in bytes, durations are in seconds, and dimensions are in pixels. Frame rates are numbers (integer or decimal) in frames per second.

Length counting

Every max_length and min_length field in the document is measured in the unit given by the top-level length_unit member, unless a field states otherwise.

Value Counts
code_points Unicode scalar values
graphemes Extended grapheme clusters as defined in UAX #29
utf16 UTF-16 code units
bytes Bytes of the UTF-8 encoding

If length_unit is absent, clients SHOULD assume code_points.

Lengths are measured on the text as the client submits it, before server-side processing such as Markdown rendering or link expansion, except where the composer’s url_weight and mention_counting members say otherwise.

Advisory nature

The configuration document is advisory. Servers MUST continue to enforce their limits independently, and clients MUST continue to handle rejection errors. A default document describes the default account. Other accounts may have different limits, which a server can express through an account-scoped document.

Top-level members

Member Type Required Description
version string Yes Configuration document version, for example "1.0".
scope string No "default" for a default document, "account" for an account-scoped document. Absent means "default".
account_scope_supported boolean No Whether the server returns account-scoped documents for authenticated requests.
software object No name (string) and version (string) of the server software. Informational only; clients SHOULD NOT branch behavior on it when the information they need is present elsewhere in the document.
length_unit string No Length counting unit. See Length counting.
media object No Media upload limits. See Media.
composer object No Post composition limits. See Composer.
accounts object No Account and profile limits. See Accounts.
links object No Human-facing web pages. See Links.
extensions object No Software-specific members. See Extensions.

Media

media object

Member Type Description
max_attachments limit Maximum number of attachments on a single post, across all types.
min_attachments integer Minimum number of attachments on a single post. 0 means text-only posts are allowed. 1 means every post requires media, as on photo-first or video-first platforms.
max_total_bytes limit Maximum combined size of all attachments on a single post.
types array Media type rules. See Media type rules.
alt_text object max_length (limit) and required (boolean). If required is true, every attachment MUST have alt text for the post to be accepted.
focal_point boolean Whether the server accepts a focal point for image attachments.

Media type rules

Each entry in media.types describes one group of mime types that share limits.

Member Type Required Description
id string Yes Identifier for this rule, unique within media.types. Short lowercase names such as image, video, audio or gif are RECOMMENDED.
mime_types array of strings Yes Mime types matched by this rule. MUST NOT be empty.
max_attachments limit No Maximum number of attachments matched by this rule on a single post.
combinable_with array of strings No ids of other rules whose attachments may appear on the same post. See Combining media types.
max_bytes limit No Maximum size of a single file.
max_width limit No Maximum width.
max_height limit No Maximum height.
max_pixels limit No Maximum width multiplied by height.
min_duration_seconds integer No Minimum duration of audio or video.
max_duration_seconds limit No Maximum duration of audio or video.
max_frame_rate number or null No Maximum frame rate of video or animated images. null means no limit.
strips_metadata boolean No Whether the server removes embedded metadata (for example EXIF, XMP and GPS location) from files of this type before storing or serving them.
transcodes boolean No Whether the server re-encodes files of this type. Clients MAY skip their own compression when true.

Mime type matching is exact and case-insensitive, and ignores parameters. Wildcards such as image/* MUST NOT be used. A mime type MUST NOT appear in more than one rule. Clients SHOULD treat a file whose mime type matches no rule as unsupported.

When a server declares dimension limits, it SHOULD state whether it rejects or downscales oversized files through transcodes: a server that downscales SHOULD set transcodes to true.

Combining media types

The rules for which attachments may share a post are:

  1. Any number of attachments matched by the same rule MAY appear on the same post, up to that rule’s max_attachments and media.max_attachments. Mime types within one rule may be freely mixed (for example a JPEG and a PNG in one album).
  2. Attachments matched by two different rules MAY appear on the same post only if each rule lists the other’s id in combinable_with.
  3. An absent combinable_with is equivalent to an empty array: the rule’s attachments cannot share a post with attachments from any other rule.
  4. combinable_with MUST be symmetric. If rule A lists B but B does not list A, clients MUST treat A and B as not combinable.
  5. A rule MUST NOT list its own id in combinable_with. Combining attachments of the same rule is governed by rule 1.

Example: photo albums, standalone video

Any mix of image formats up to 20, or a single video, never both:

"types": [
  {
    "id": "image",
    "mime_types": ["image/jpeg", "image/png", "image/webp", "image/avif"],
    "max_attachments": 20,
    "max_bytes": 15000000,
    "strips_metadata": true
  },
  {
    "id": "video",
    "mime_types": ["video/mp4", "video/webm"],
    "max_attachments": 1,
    "max_bytes": 100000000,
    "max_duration_seconds": 600,
    "strips_metadata": false
  }
]

Images and videos may share a post, up to 10 attachments in total:

"max_attachments": 10,
"types": [
  { "id": "image", "mime_types": ["image/jpeg", "image/png"], "combinable_with": ["video"] },
  { "id": "video", "mime_types": ["video/mp4"], "combinable_with": ["image"], "max_duration_seconds": 60 }
]

Composer

composer object

Member Type Description
allowed boolean Whether the account may create posts. false means it cannot post at all, for example a read-only role. Default documents SHOULD NOT set this to false, since the default account is by definition allowed to post.
max_length limit Maximum length of the post body.
url_weight integer or null If an integer, every URL in the post body counts as exactly this many length units, regardless of its actual length. If null or absent, URLs are counted literally.
mention_counting string full (default): a mention such as @alice@example.com counts in full. local_part: only @alice counts; the @domain part is free.
content_types array of strings Mime types the server accepts for the post body, for example text/plain, text/markdown, text/html.
content_warning object See below.
polls object See below.
visibility array of strings Supported visibility values. See Visibility values.
editing object See below.
scheduling object See below.
quotes object supported (boolean): whether the server allows quote posts.
max_mentions limit Maximum number of mentions in a single post.
max_hashtags limit Maximum number of hashtags in a single post.
languages object supported (array of BCP 47 tags, or null for any language) and required (boolean: whether a post MUST declare its language).

content_warning

Member Type Description
supported boolean Whether posts may carry a content warning (summary).
max_length limit Maximum length of the content warning.
counts_toward_max_length boolean If true, the content warning’s length is added to the body’s length when checking composer.max_length.

polls

Member Type Description
supported boolean Whether posts may include a poll.
min_options integer Minimum number of options.
max_options limit Maximum number of options.
max_option_length limit Maximum length of each option.
multiple_choice boolean Whether polls may allow more than one choice.
min_expiration_seconds integer Shortest allowed poll duration.
max_expiration_seconds limit Longest allowed poll duration.

editing

Member Type Description
supported boolean Whether published posts may be edited.
window_seconds limit How long after publishing a post may be edited.
max_edits limit Maximum number of edits per post.

scheduling

Member Type Description
supported boolean Whether posts may be scheduled for future publication.
min_lead_seconds integer Minimum time between scheduling and publication.
max_lead_seconds limit Maximum time between scheduling and publication.
max_scheduled limit Maximum number of pending scheduled posts per account.

Visibility values

Value Meaning
public Visible to anyone and eligible for public timelines.
unlisted Visible to anyone, but excluded from public timelines and discovery features.
followers Delivered to and visible to the author’s followers only.
direct Delivered to and visible to mentioned recipients only.
local Visible only to accounts on the same server, and not federated.

Software-specific visibility values MUST be absolute URLs.

Accounts

accounts object

Member Type Description
username object See Username rules.
display_name object max_length (limit).
bio object max_length (limit).
fields object Profile metadata fields: max_count (limit), name_max_length (limit), value_max_length (limit), link_verification (boolean: whether the server verifies links in field values, for example with rel="me").
avatar object Image rule: mime_types (array), max_bytes (limit), max_width (limit), max_height (limit).
header object Image rule, same shape as avatar.
max_pinned_posts limit Maximum number of pinned posts.
max_featured_tags limit Maximum number of featured hashtags on a profile.
storage_quota_bytes limit Total media storage available to an account.
password object min_length (integer) and max_length (limit).
two_factor object methods: array of supported second-factor methods. See Two-factor methods. An empty array means two-factor authentication is not supported.
follow_approval boolean Whether accounts may require manual approval of new followers.
migration object move_in (boolean: whether the server accepts accounts moving in from other servers), move_out (boolean: whether accounts may move to another server), max_aliases (limit: maximum number of account aliases).

Username rules

Member Type Description
min_length integer Minimum username length.
max_length limit Maximum username length.
pattern string A regular expression a valid username MUST match. See below.
allowed_characters array of strings A summary of character classes permitted in usernames. See below.
case_insensitive boolean If true, usernames differing only in letter case identify the same account.
changeable boolean Whether a user may change their username after registration.
change_cooldown_seconds integer Minimum time between username changes.

Usernames are the local part only, without a leading @ or a domain.

pattern

allowed_characters

Value Characters
lowercase_ascii a to z
uppercase_ascii A to Z
digits 0 to 9
underscore _
period .
hyphen -
unicode_letters Any character with the Unicode Letter general category
unicode_digits Any character with the Unicode Decimal_Number general category

Using both

pattern is authoritative: it captures positional rules (for example “must start with a letter” or “no trailing period”) that allowed_characters cannot. allowed_characters exists for help text (“Letters, numbers and underscores”) and for clients that cannot or will not evaluate a regular expression.

When both are present, they MUST be consistent: every character class listed in allowed_characters MUST be accepted by pattern in at least one position, and pattern MUST NOT accept characters outside the listed classes. Clients that can evaluate pattern SHOULD use it for validation and use allowed_characters for display.

Two-factor methods

Value Method
totp Time-based one-time passwords, RFC 6238
webauthn WebAuthn security keys and passkeys
email One-time codes delivered by email

Software-specific method values MUST be absolute URLs.

The links object lists web pages intended for humans, not API endpoints. Every member is OPTIONAL. Every value MUST be an absolute https URL.

Member Page
registration Account sign-up
login Web sign-in
password_reset Password reset request
account_settings General account settings
two_factor_settings Two-factor authentication setup and management
account_deletion Account deletion
data_export Account data export
about About the server
rules Server rules
terms Terms of service
privacy Privacy policy
support Help or contact page
status Service status page
donate Funding or donation page for the server

Clients SHOULD open these pages in the user’s system browser rather than an embedded web view, so users can verify the address and use their password manager. Pages not listed here MUST be placed under extensions.

Extensions

The extensions object holds software-specific configuration. Each key MUST be an absolute URL that identifies the extension and SHOULD dereference to its documentation. Values MAY be any JSON value.

"extensions": {
  "https://pixelfed.org/ns/client-config#collections": {
    "max_collections": 100,
    "max_posts_per_collection": 50
  }
}

Clients MUST ignore extension keys they do not recognize. Implementers SHOULD propose broadly useful extensions for inclusion in a future minor version of this FEP rather than relying on extensions indefinitely.

Non-Goals

This FEP intentionally does not cover:

Security and Privacy Considerations

IANA Considerations

This FEP requests registration of the following well-known URI in the “Well-Known URIs” registry established by RFC 8615:

Full Example

Discovery document at https://example.social/.well-known/activitypub-client-config:

{
  "links": [
    {
      "rel": "https://w3id.org/fep/65ca/1.0",
      "href": "https://example.social/api/client-config/1.0"
    }
  ]
}

Default document at https://example.social/api/client-config/1.0:

{
  "version": "1.0",
  "scope": "default",
  "account_scope_supported": true,
  "software": { "name": "examplesoft", "version": "2.4.0" },
  "length_unit": "code_points",
  "media": {
    "max_attachments": 20,
    "min_attachments": 1,
    "max_total_bytes": null,
    "types": [
      {
        "id": "image",
        "mime_types": ["image/jpeg", "image/png", "image/webp", "image/avif"],
        "max_attachments": 20,
        "max_bytes": 15000000,
        "max_pixels": 16777216,
        "strips_metadata": true,
        "transcodes": true
      },
      {
        "id": "video",
        "mime_types": ["video/mp4", "video/webm"],
        "max_attachments": 1,
        "max_bytes": 100000000,
        "max_width": 3840,
        "max_height": 2160,
        "max_duration_seconds": 600,
        "max_frame_rate": 60,
        "strips_metadata": false,
        "transcodes": true
      }
    ],
    "alt_text": { "max_length": 2000, "required": false },
    "focal_point": false
  },
  "composer": {
    "allowed": true,
    "max_length": 2000,
    "url_weight": 23,
    "mention_counting": "local_part",
    "content_types": ["text/plain"],
    "content_warning": {
      "supported": true,
      "max_length": 500,
      "counts_toward_max_length": false
    },
    "polls": {
      "supported": true,
      "min_options": 2,
      "max_options": 4,
      "max_option_length": 50,
      "multiple_choice": true,
      "min_expiration_seconds": 300,
      "max_expiration_seconds": 2629746
    },
    "visibility": ["public", "unlisted", "followers", "direct"],
    "editing": { "supported": true, "window_seconds": 86400, "max_edits": null },
    "scheduling": { "supported": false },
    "quotes": { "supported": true },
    "max_mentions": 5,
    "max_hashtags": 30,
    "languages": { "supported": null, "required": false }
  },
  "accounts": {
    "username": {
      "min_length": 2,
      "max_length": 30,
      "pattern": "^[a-zA-Z0-9_](?:[a-zA-Z0-9_.]*[a-zA-Z0-9_])?$",
      "allowed_characters": ["lowercase_ascii", "uppercase_ascii", "digits", "underscore", "period"],
      "case_insensitive": true,
      "changeable": true,
      "change_cooldown_seconds": 2592000
    },
    "display_name": { "max_length": 64 },
    "bio": { "max_length": 500 },
    "fields": {
      "max_count": 4,
      "name_max_length": 255,
      "value_max_length": 255,
      "link_verification": true
    },
    "avatar": {
      "mime_types": ["image/jpeg", "image/png", "image/webp"],
      "max_bytes": 2000000,
      "max_width": 1000,
      "max_height": 1000
    },
    "header": {
      "mime_types": ["image/jpeg", "image/png", "image/webp"],
      "max_bytes": 5000000
    },
    "max_pinned_posts": 3,
    "max_featured_tags": 10,
    "storage_quota_bytes": 1073741824,
    "password": { "min_length": 12, "max_length": 128 },
    "two_factor": { "methods": ["totp", "webauthn"] },
    "follow_approval": true,
    "migration": { "move_in": true, "move_out": true, "max_aliases": 5 }
  },
  "links": {
    "registration": "https://example.social/register",
    "login": "https://example.social/login",
    "password_reset": "https://example.social/password/reset",
    "account_settings": "https://example.social/settings",
    "two_factor_settings": "https://example.social/settings/security",
    "account_deletion": "https://example.social/settings/delete",
    "data_export": "https://example.social/settings/export",
    "about": "https://example.social/about",
    "rules": "https://example.social/rules",
    "terms": "https://example.social/terms",
    "privacy": "https://example.social/privacy",
    "support": "https://example.social/help",
    "status": "https://status.example.social",
    "donate": "https://example.social/donate"
  },
  "extensions": {
    "https://examplesoft.org/ns/client-config#collections": {
      "max_collections": 100
    }
  }
}

Account-scoped example

A blog server where new accounts are read-only subscribers, and authors can post and upload. An author’s client sends its bearer token:

GET /api/client-config/1.0 HTTP/1.1
Host: example.blog
Authorization: Bearer 6f1c9e...

The server responds with the author’s effective limits:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *
Cache-Control: private, max-age=600
Vary: Authorization
ETag: "a91f3c"
{
  "version": "1.0",
  "scope": "account",
  "account_scope_supported": true,
  "length_unit": "code_points",
  "media": {
    "max_attachments": 10,
    "min_attachments": 0,
    "types": [
      {
        "id": "image",
        "mime_types": ["image/jpeg", "image/png", "image/webp"],
        "max_bytes": 8000000
      }
    ]
  },
  "composer": {
    "allowed": true,
    "max_length": null,
    "content_types": ["text/html", "text/markdown"],
    "visibility": ["public", "followers"]
  }
}

The same request made with a subscriber’s token returns a document with "scope": "account" and "composer": { "allowed": false }. The same request made with no token, or with an expired one, returns the default document with "scope": "default".

JSON Schema

Non-normative JSON Schema files are published alongside this FEP: discovery.schema.json for the discovery document, and client-config.schema.json for the configuration document. Where a schema and this document disagree, this document is authoritative.

Implementations

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.