PocketBase logo PocketBase v0.28.1
FAQ Documentation
Introduction Going to production Web APIs reference ├ API Records ├ API Realtime ├ API Files ├ API Collections ├ API Settings ├ API Logs ├ API Crons ├ API Backups └ API Health
Extend with
Go
Extend with
JavaScript
Go Overview Go Event hooks Go Routing Go Database Go Record operations Go Collection operations Go Migrations Go Jobs scheduling Go Sending emails Go Rendering templates Go Console commands Go Realtime messaging Go Filesystem Go Logging Go Testing Go Miscellaneous Go Record proxy
JS Overview JS Event hooks JS Routing JS Database JS Record operations JS Collection operations JS Migrations JS Jobs scheduling JS Sending emails JS Rendering templates JS Console commands JS Sending HTTP requests JS Realtime messaging JS Filesystem JS Logging JS Types reference
Web APIs reference - API Settings
API Settings

Returns a list with all available application settings.

Secret/password fields are automatically redacted with ****** characters.

Only superusers can perform this action.

import PocketBase from 'pocketbase'; const pb = new PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); const settings = await pb.settings.getAll();
import 'package:pocketbase/pocketbase.dart'; final pb = PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); final settings = await pb.settings.getAll();
API details
GET
/api/settings
Requires Authorization:TOKEN
Query parameters
Param Type Description
fields String

Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.:

?fields=*,expand.relField.name

* targets all keys from the specific depth level.

In addition, the following field modifiers are also supported:

  • :excerpt(maxLength, withEllipsis?)
    Returns a short plain text version of the field string value.
    Ex.: ?fields=*,description:excerpt(200,true)
Responses
{ "smtp": { "enabled": false, "port": 587, "host": "smtp.example.com", "username": "", "authMethod": "", "tls": true, "localName": "" }, "backups": { "cron": "0 0 * * *", "cronMaxKeep": 3, "s3": { "enabled": false, "bucket": "", "region": "", "endpoint": "", "accessKey": "", "forcePathStyle": false } }, "s3": { "enabled": false, "bucket": "", "region": "", "endpoint": "", "accessKey": "", "forcePathStyle": false }, "meta": { "appName": "Acme", "appURL": "https://example.com", "senderName": "Support", "senderAddress": "support@example.com", "hideControls": false }, "rateLimits": { "rules": [ { "label": "*:auth", "audience": "", "duration": 3, "maxRequests": 2 }, { "label": "*:create", "audience": "", "duration": 5, "maxRequests": 20 }, { "label": "/api/batch", "audience": "", "duration": 1, "maxRequests": 3 }, { "label": "/api/", "audience": "", "duration": 10, "maxRequests": 300 } ], "enabled": false }, "trustedProxy": { "headers": [], "useLeftmostIP": false }, "batch": { "enabled": true, "maxRequests": 50, "timeout": 3, "maxBodySize": 0 }, "logs": { "maxDays": 7, "minLevel": 0, "logIP": true, "logAuthId": false } }
{ "status": 401, "message": "The request requires valid record authorization token.", "data": {} }
{ "status": 403, "message": "The authorized record is not allowed to perform this action.", "data": {} }

Bulk updates application settings and returns the updated settings list.

Only superusers can perform this action.

import PocketBase from 'pocketbase'; const pb = new PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '123456'); const settings = await pb.settings.update({ meta: { appName: 'YOUR_APP', appUrl: 'http://127.0.0.1:8090', }, });
import 'package:pocketbase/pocketbase.dart'; final pb = PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '123456'); final settings = await pb.settings.update(body: { 'meta': { 'appName': 'YOUR_APP', 'appUrl': 'http://127.0.0.1:8090', }, });
API details
PATCH
/api/settings
Requires Authorization:TOKEN
Body Parameters
Param Type Description
meta
Application meta data (name, url, support email, etc.).
├─ Required appName
String The app name.
├─ Required appUrl
String The app public absolute url.
├─ Optional hideControls
Boolean Hides the collection create and update controls from the Dashboard. Useful to prevent making accidental schema changes when in production environment.
├─ Required senderName
String Transactional mails sender name.
├─ Required senderAddress
String Transactional mails sender address.
logs
App logger settings.
└─ Optional maxDays
Number Max retention period. Set to 0 for no logs.
└─ Optional minLevel
Number Specifies the minimum log persistent level.
The default log levels are:
  • -4: DEBUG
  • 0: INFO
  • 4: WARN
  • 8: ERROR
└─ Optional logIP
Boolean If enabled includes the client IP in the activity request logs.
└─ Optional logAuthId
Boolean If enabled includes the authenticated record id in the activity request logs.
backups
App data backups settings.
├─ Optional cron
String Cron expression to schedule auto backups, e.g. 0 0 * * *.
├─ Optional cronMaxKeep
Number The max number of cron generated backups to keep before removing older entries.
└─ Optional s3
Object S3 configuration (the same fields as for the S3 file storage settings).
smtp
SMTP mail server settings.
├─ Optional enabled
Boolean Enable the use of the SMTP mail server for sending emails.
├─ Required host
String Mail server host (required if SMTP is enabled).
├─ Required port
Number Mail server port (required if SMTP is enabled).
├─ Optional username
String Mail server username.
├─ Optional password
String Mail server password.
├─ Optional tls
Boolean Whether to enforce TLS connection encryption.
When false StartTLS command is send, leaving the server to decide whether to upgrade the connection or not).
├─ Optional authMethod
String The SMTP AUTH method to use - PLAIN or LOGIN (used mainly by Microsoft).
Default to PLAIN if empty.
└─ Optional localName
String Optional domain name or (IP address) to use for the initial EHLO/HELO exchange.
If not explicitly set, localhost will be used.
Note that some SMTP providers, such as Gmail SMTP-relay, requires a proper domain name and and will reject attempts to use localhost.
s3
S3 compatible file storage settings.
├─ Optional enabled
Boolean Enable the use of a S3 compatible storage.
├─ Required bucket
String S3 storage bucket (required if enabled).
├─ Required region
String S3 storage region (required if enabled).
├─ Required endpoint
String S3 storage public endpoint (required if enabled).
├─ Required accessKey
String S3 storage access key (required if enabled).
├─ Required secret
String S3 storage secret (required if enabled).
└─ Optional forcePathStyle
Boolean Forces the S3 request to use path-style addressing, e.g. "https://s3.amazonaws.com/BUCKET/KEY" instead of the default "https://BUCKET.s3.amazonaws.com/KEY".
batch
Batch logs settings.
├─ Optional enabled
Boolean Enable the batch Web APIs.
├─ Required maxRequests
Number The maximum allowed batch request to execute.
├─ Required timeout
Number The max duration in seconds to wait before cancelling the batch transaction.
└─ Optional maxBodySize
Number The maximum allowed batch request body size in bytes.
If not set, fallbacks to max ~128MB.
rateLimits
Rate limiter settings.
├─ Optional enabled
Boolean Enable the builtin rate limiter.
└─ Optional rules
Array<RateLimitRule> List of rate limit rules. Each rule have:
  • label - the identifier of the rule.
    It could be a tag, complete path or path prerefix (when ends with `/`).
  • maxRequests - the max allowed number of requests per duration.
  • duration - specifies the interval (in seconds) per which to reset the counted/accumulated rate limiter tokens..
trustedProxy
Trusted proxy headers settings.
├─ Optional headers
Array<String> List of explicit trusted header(s) to check.
└─ Optional useLeftmostIP
Boolean Specifies to use the left-mostish IP from the trusted headers.
Body parameters could be sent as JSON or multipart/form-data.
Query parameters
Param Type Description
fields String

Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.:

?fields=*,expand.relField.name

* targets all keys from the specific depth level.

In addition, the following field modifiers are also supported:

  • :excerpt(maxLength, withEllipsis?)
    Returns a short plain text version of the field string value.
    Ex.: ?fields=*,description:excerpt(200,true)
Responses
{ "smtp": { "enabled": false, "port": 587, "host": "smtp.example.com", "username": "", "authMethod": "", "tls": true, "localName": "" }, "backups": { "cron": "0 0 * * *", "cronMaxKeep": 3, "s3": { "enabled": false, "bucket": "", "region": "", "endpoint": "", "accessKey": "", "forcePathStyle": false } }, "s3": { "enabled": false, "bucket": "", "region": "", "endpoint": "", "accessKey": "", "forcePathStyle": false }, "meta": { "appName": "Acme", "appURL": "https://example.com", "senderName": "Support", "senderAddress": "support@example.com", "hideControls": false }, "rateLimits": { "rules": [ { "label": "*:auth", "audience": "", "duration": 3, "maxRequests": 2 }, { "label": "*:create", "audience": "", "duration": 5, "maxRequests": 20 }, { "label": "/api/batch", "audience": "", "duration": 1, "maxRequests": 3 }, { "label": "/api/", "audience": "", "duration": 10, "maxRequests": 300 } ], "enabled": false }, "trustedProxy": { "headers": [], "useLeftmostIP": false }, "batch": { "enabled": true, "maxRequests": 50, "timeout": 3, "maxBodySize": 0 }, "logs": { "maxDays": 7, "minLevel": 0, "logIP": true, "logAuthId": false } }
{ "status": 400, "message": "An error occurred while submitting the form.", "data": { "meta": { "appName": { "code": "validation_required", "message": "Missing required value." } } } }
{ "status": 401, "message": "The request requires valid record authorization token.", "data": {} }
{ "status": 403, "message": "The authorized record is not allowed to perform this action.", "data": {} }

Performs a S3 storage connection test.

Only superusers can perform this action.

import PocketBase from 'pocketbase'; const pb = new PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); await pb.settings.testS3("backups");
import 'package:pocketbase/pocketbase.dart'; final pb = PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); await pb.settings.testS3("backups");
API details
POST
/api/settings/test/s3
Requires Authorization:TOKEN
Body Parameters
Param Type Description
Required filesystem
String The storage filesystem to test (storage or backups).
Body parameters could be sent as JSON or multipart/form-data.
Responses
null
{ "status": 400, "message": "Failed to initialize the S3 storage. Raw error:...", "data": {} }
{ "status": 401, "message": "The request requires valid record authorization token.", "data": {} }

Sends a test user email.

Only superusers can perform this action.

import PocketBase from 'pocketbase'; const pb = new PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); await pb.settings.testEmail("test@example.com", "verification");
import 'package:pocketbase/pocketbase.dart'; final pb = PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); await pb.settings.testEmail("test@example.com", "verification");
API details
POST
/api/settings/test/email
Requires Authorization:TOKEN
Body Parameters
Param Type Description
Optional collection
String The name or id of the auth collection. Fallbacks to _superusers if not set.
Required email
String The receiver of the test email.
Required template
String The test email template to send:
verification, password-reset or email-change.
Body parameters could be sent as JSON or multipart/form-data.
Responses
null
{ "status": 400, "message": "Failed to send the test email.", "data": { "email": { "code": "validation_required", "message": "Missing required value." } } }
{ "status": 401, "message": "The request requires valid record authorization token.", "data": {} }

Generates a new Apple OAuth2 client secret key.

Only superusers can perform this action.

import PocketBase from 'pocketbase'; const pb = new PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); await pb.settings.generateAppleClientSecret(clientId, teamId, keyId, privateKey, duration)
import 'package:pocketbase/pocketbase.dart'; final pb = PocketBase('http://127.0.0.1:8090'); ... await pb.collection("_superusers").authWithPassword('test@example.com', '1234567890'); await pb.settings.generateAppleClientSecret(clientId, teamId, keyId, privateKey, duration)
API details
POST
/api/settings/apple/generate-client-secret
Requires Authorization:TOKEN
Body Parameters
Param Type Description
Required clientId
String The identifier of your app (aka. Service ID).
Required teamId
String 10-character string associated with your developer account (usually could be found next to your name in the Apple Developer site).
Required keyId
String 10-character key identifier generated for the "Sign in with Apple" private key associated with your developer account.
Required privateKey
String PrivateKey is the private key associated to your app.
Required duration
Number Duration specifies how long the generated JWT token should be considered valid.
The specified value must be in seconds and max 15777000 (~6months).
Body parameters could be sent as JSON or multipart/form-data.
Responses
{ "secret": "..." }
{ "status": 400, "message": "Failed to generate client secret. Raw error:...", "data": {} }
{ "status": 401, "message": "The request requires valid record authorization token.", "data": {} }

Prev: API Collections Next: API Logs
FAQ Discussions Documentation
JavaScript SDK Dart SDK
PocketBase
© 2023-2025 PocketBase The Gopher artwork is from marcusolsson/gophers
Crafted by Gani