Reports which optional parts of the service this instance exposes.
Answers to everyone, signed in or not, since a client needs this before it
can know whether logging in is possible. An administrator gets one extra
field; see [Capabilities::storage_remaining_bytes].
Errors
Only when the storage total cannot be read: an administrator's request against a database that is not answering.
tessera_session<token>Set by POST /auth/login. A browser sends it automatically; it is HttpOnly, so page scripts cannot read or set it.
What this instance exposes
application/json- response
Body of GET /api/v1/capabilities.
Why this endpoint exists
openapi.json is a build artefact describing every endpoint the software
has. Which of them an instance exposes is a runtime decision its operator
made, so a single-page app generated from the contract cannot know whether
to render a login button: the contract says login exists, and on this
deployment it may not.
So the contract describes the whole surface and this reports the subset in force. It is unauthenticated, because a client needs the answer before it can know whether logging in is possible at all.
access_log*booleanWhether this instance writes down who fetches a share.
false by default. When true, every retrieval records the visitor's
address and browser string, and the visitor is the person it happens to,
so a client should say so on the page where the share is collected.
Nothing else will.
account_password_breach_check*booleanWhether a new account password is checked against known breaches, so a
form can look it up while typing; see GET /auth/pwned/{prefix}.
account_password_min_length*integerShortest account password this instance accepts, so a client can say so before the round trip, not after it.
Named for what it governs, because there are two minimums and they
differ. See
share_password_min_length.
0 <= valueaccount_password_requires_digit*booleanWhether an account password needs a digit.
account_password_requires_mixed_case*booleanWhether an account password needs both an uppercase and a lowercase
letter. Character classes are defined on PasswordPolicy; a client that
classifies differently will accept passwords the server refuses.
account_password_requires_symbol*booleanWhether an account password needs a symbol. A space is not one.
accounts*booleanWhether accounts exist at all on this instance.
false means no registration, no login and no session: the shape for a
personal instance behind a VPN.
admin*booleanWhether the administrative endpoints are mounted.
The administration front-end is a separate deployment, so this says only that the API half is present.
anonymous_upload*booleanWhether a caller without a session may upload.
Independent of accounts: an instance can have
accounts and accept anonymous uploads, the default.
code_length*integerNumber of characters in a retrieval code on this instance
(share.code_length), so the page that collects one can draw the right
number of boxes. Codes already issued keep the length they had, so this
is what new shares get, not a promise about every code in existence.
1 <= valuedefault_expiry_hours?|How long a share lasts when the uploader does not choose, in hours.
The upload form needs this to say what "leave it alone" means. null
when this instance lets shares live forever by default.
int640 <= valueencryption*booleanWhether an upload may be end-to-end encrypted. See docs/encryption.md.
max_expiry_hours?|The longest lifetime an uploader may ask for, in hours.
null when there is no ceiling. A form that knows this can bound its own
control instead of offering a date the server will refuse.
int640 <= valuemax_upload_bytes*integerLargest single file this caller may send, in bytes.
The narrowest of their own limit, their role's and
server.max_body_bytes. So an operator who raised the instance figure
for themselves does not have it reported to every stranger, and a client
is never shown a number bigger than what it may send.
int640 <= valuepassword_reset*booleanWhether this instance can send a password reset link.
false when no relay is configured, the default. A client that
drew the "forgot password" link regardless would send people to an
endpoint answering 404, so this is the difference between a missing
feature and a broken one.
registration*RegistrationPolicyWho may create an account. Meaningless when
accounts is false.
"open""invite""closed"registration_requires_confirmation*booleanWhether registering sends a confirmation link instead of creating the account outright.
true means POST /auth/register answers 202 and nothing exists
until the address is confirmed, so a client must show "check your inbox"
instead of treating the response as a sign-in. false means it answers
201 with a session, as an instance sending no mail does.
share_password_min_length*integerShortest password an uploader may put on a share.
Lower than the account minimum by design. A share password is a second factor on a link that is already unguessable, and it gets read out over the phone. A form that validated share passwords against the account rule would refuse the four-digit code the server would have accepted.
0 <= valuespeed_test*booleanWhether this caller may run a speed test.
Per caller, not per instance: an instance can offer the test to accounts but not visitors, and a visitor should see the same as on an instance without the test.
storage_remaining_bytes?|How much room the caller has left, in bytes.
Whichever ceiling refuses them first: their own quota, then their
role's. Callers who may read instance statistics also see the instance
ceiling. null if none applies.
storage.max_total_bytes is not in everybody's answer because on a
public instance it is the operator's capacity planning, and telling
every anonymous uploader how close the disk is to full invites them to
finish it off. Their own quota is theirs to know, and a client holding
it can say so before they pick a file.
int640 <= valueversion*stringVersion of the running server, for a client that wants to warn about a mismatch with the contract it was generated from.
curl -X GET 'https://example.com/api/v1/capabilities'{ "access_log": true, "account_password_breach_check": true, "account_password_min_length": 0, "account_password_requires_digit": true, "account_password_requires_mixed_case": true, "account_password_requires_symbol": true, "accounts": true, "admin": true, "anonymous_upload": true, "code_length": 1, "default_expiry_hours": 0, "encryption": true, "max_expiry_hours": 0, "max_upload_bytes": 0, "password_reset": true, "registration": "open", "registration_requires_confirmation": true, "share_password_min_length": 0, "speed_test": true, "storage_remaining_bytes": 0, "version": "string"}