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.
Clients that support more than one kind of fediverse server currently face a bad set of options:
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.
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.
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.
/.well-known/activitypub-client-config.max_length or max_bytes).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:
href MUST have the same origin as the discovery document request. A client talks to a known API host, and the configuration document describes that host.rel they do not recognize.Fetching the href MUST return HTTP status 200, a Content-Type of application/json, and a body conforming to Configuration Document.
These requirements apply to both the discovery document and the configuration document.
Access-Control-Allow-Origin: * so that browser-based clients on other origins can read them. Servers SHOULD also include Access-Control-Expose-Headers: ETag.Cache-Control with a max-age between 3600 and 86400 seconds, and SHOULD send an ETag or Last-Modified header. Clients SHOULD cache both documents, SHOULD revalidate at least once every 24 hours, and SHOULD refetch the configuration document when the server rejects a request in a way that contradicts the cached configuration. Account-scoped documents have additional caching rules, described below.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.
A server that supports account-scoped documents:
Authorization request header, carrying a credential the server accepts for its client API, typically an OAuth 2.0 bearer token (RFC 6750). It MUST NOT select the document using cookies or other ambient credentials.200 when the Authorization header is absent, invalid or expired. It MUST NOT respond with 401 or 403, so that the endpoint stays usable for every client.scope to "account" in an account-scoped document, and MUST set account_scope_supported to true in every configuration document it serves, default or account-scoped.composer.allowed set to false.Vary: Authorization on every configuration document response, default or account-scoped.Cache-Control: private on account-scoped responses, MUST NOT send public or s-maxage on them, and SHOULD use a max-age no greater than 3600 seconds.OPTIONS) request for the configuration document with Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET and Access-Control-Allow-Headers: Authorization. Browsers send a preflight before any cross-origin request carrying an Authorization header.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.
account_scope_supported is true, clients SHOULD fetch the configuration document again with the account’s credential, and SHOULD use the account-scoped document for that account.scope. If an authenticated request returns a document whose scope is "default" or absent, the credential was not accepted or the server does not support account-scoped documents, and the limits may not match the signed-in account.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.
null on a limit field means there is no limit.0 on a limit field means the thing is not allowed. For example, "max_attachments": 0 means posts cannot carry attachments.null MUST NOT be used on non-limit fields.
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.
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.
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.
| 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 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. |
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.
The rules for which attachments may share a post are:
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).id in combinable_with.combinable_with is equivalent to an empty array: the rule’s attachments cannot share a post with attachments from any other rule.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.id in combinable_with. Combining attachments of the same rule is governed by rule 1.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 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. |
| 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 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). |
| 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.
patternu flag.^ and end with $.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 |
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.
| 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.
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.
This FEP intentionally does not cover:
links object points to these pages but does not reproduce them.Authorization unless the response explicitly allows it, which is why public and s-maxage are not allowed on account-scoped responses. Some CDNs still need explicit configuration.links object, especially when it differs from the server’s host.pattern designed to cause excessive backtracking. Clients SHOULD bound the time spent evaluating pattern, and SHOULD fall back to allowed_characters and length checks when evaluation fails or times out.strips_metadata set to false or absent, clients SHOULD inform users that embedded metadata such as GPS location may be published, and SHOULD offer to remove it before upload.This FEP requests registration of the following well-known URI in the “Well-Known URIs” registry established by RFC 8615:
activitypub-client-configDiscovery 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
}
}
}
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".
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.
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.