--- title: "Service: /setup [POST]" source: https://dev.pageseeder.com/api/services/setup_post.html description: "API endpoint for handling PageSeeder configuration, including database settings, SMTP server credentials, website details, and license information. It supports setup initialization and updates for administrators." last_updated: 2026-09-08T11:53:15+10:00 document_type: api_endpoint operation_id: system-POST resource_id: system path_template: /setup http_method: POST api_category: system implementation_version: 6.0000 api_since: 4.0100 deprecated_since: null obsolete_since: null api_support: experimental cache_control: N/A generated_at: 2025-08-04 tokens: ~2582 --- # /setup \[POST\] ## Description Handles PageSeeder configuration setup. Usage: ```text /api/setup /api/setup.xml /api/setup.json ``` ### Default database URL The default database URL is computed as: | Datebase type | Default database URL | | --- | --- | | `MySQL`  | `jdbc:mysql://{host}/{database}` | | `PostgreSQL`  | `jdbc:postgresql://{host}/{database}`  | ## Parameters The following parameters are always supported by this service. | Name | Description | Required | Type | Default\* | | --- | --- | --- | --- | --- | | updatedatabase | Indicates that the database settings should be updated if equal to 'yes' | no | boolean | `false` | | smtpserveraddress | The address of the SMTP server to use | no | string | `localhost` | | smtpserverport | SMTP server user port | no | integer | `25` | | smtpserverusername | SMTP server user name when using authentication | no | string | (empty) | | smtpserverpassword | SMTP server password when using authentication | no | string | (empty) | | smtpserverssl | To use SSL to connect to SMTP server | no | boolean | `false` | | smtpserverstarttls | To Use StartTLS to connect to SMTP server | no | boolean | `false` | | websiteaddress | The host of the URL users access PageSeeder with | no | string | `localhost` | | websiteport | The port of the URL users access PageSeeder with | no | integer | `443` | | websitescheme | The scheme of the URL users access PageSeeder with | no | enum | `https` | | emaildomain | The domain for emails sent to PageSeeder (if blank incoming emails are disabled) | no | string | | | productkey | The PageSeeder product key | no | string | `dev` | | projects | The maximum number of projects allowed by the license (integer or 'unlimited') | no | string | `unlimited` | | groups | The maximum number of groups allowed by the license (integer or 'unlimited') | no | string | `unlimited` | | members | The maximum number of members allowed by the license (integer or 'unlimited') | no | string | `unlimited` | | licenseexpires | The date the license expires ('YYYY-MM-DD' or '') | no | date | | > **Note:** \* If a default value is specified in this column and setup has been run previously, the default values are the values previously submitted. ### Update database If the updatedatabase parameter is set to `true`, the following parameters are supported: | Name | Description | Required | Type | Default\* | | --- | --- | --- | --- | --- | | dbtype | The type of database - 'MySQL', 'PostgreSQL' | yes | enum | | | dbhostname | Where the database is hosted | yes | string | | | dbname | The name of the database, for example, 'pageseeder' | yes | string | | | dburl | A custom URL for accessing the database | no | string | *Default database URL* | | dbloginname | The new login name to the database server | yes | string | | | dbloginpassword | The new password to the database server  | yes | string | | | createdatabase | Indicates that the database should be created | no | boolean | `false` | | createtables | Indicates that the database tables should be created | no | boolean | `false` | ### Create database If the createdatabase parameter is set to `true` , the following parameters are supported to provide the credentials of the database administrator: | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | dbaloginname | The current database administrator login name | yes | string | | | dbaloginpassword | The current database administrator password | yes | string | | > **Tip:** The database administrator credentials are not stored in PageSeeder – they are only used for creating the PageSeeder database. ### Create tables If the createtables parameter is set to `true` , the following parameters are supported to provide the details of the PageSeeder administrator to create: | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | adminfirstname | The first name of the PageSeeder Administrator to create | yes | string | | | adminsurname | The last name of the PageSeeder Administrator to create | yes | string | | | adminusername | The username of the PageSeeder Administrator to create | no | string | *admin email* | | adminemail | The email of the PageSeeder Administrator to create | yes | string | | | adminpassword | The password of the PageSeeder Administrator to create | yes | string | | ## Permission If the value of `DBURL` [database property](../../guide/configuration/properties/database_properties.md) is empty, this service can be invoked without authentication as PageSeeder assumes that the setup has not been completed. Otherwise, only administrators can invoke it. ## Response The response is a reflection of changes made by this service and includes the values from the [global](../../guide/configuration/properties/global_properties.md) and database properties used to set up PageSeeder. | Field | Description | Type | | --- | --- | --- | | `licenseexpired` | If the `licenseExpires` global property is specified and earlier than today’s date | `boolean` | | `loginrequired` | Set to `true` if the database or administrator details have been modified | `boolean` | | `productkeyinvalid` | Set to `true` if the product key is not valid | `boolean` | | `organizationdisabled`  | If there is an existing organization config and it is disabled because the product key is not of type "Service provider" | `boolean` | | `organizationerror` | If there was an error loading the organization config | `boolean` | | `smtpserveraddress` | Value of `smtpServerAddress` global property | `host`  | | `smtpserverpor` | Value of `smtpServerPort` global property | `port`  | | `smtpserverusername` | Value of `smtpServerUsername` global property | `string` | | `smtpserverssl` | Value of `smtpServerSSL` global property | `boolean` | | `smtpserverstarttls` | Value of `smtpServerSTARTTLS` global property | `boolean` | | `productkey` | Value of `productKey` global property | `string`  | | `projects` | Value of `projects` global property, a number or `unlimited` (default to `unlimited`),  | `string`  | | `groups` | Value of `groups` global property, a number or `unlimited` (default to `unlimited`) | `string`  | | `members` | Value of `members` global property, a number or `unlimited` (default to `unlimited`) | `string`  | | `licenseexpires` | Value of `licenseExpires` global property | `date` | | `websiteaddress` | Value of `webSiteAddress` global property | `host`  | | `websitescheme` | Value of `webSiteScheme` global property | `string` | | `websiteport` | Value of `webSitePort` global property | `port` | | `emaildomain` | Value of `emailDomain` global property | `host` | | `dbtype` | Value of `DatabaseType` database property | `string` | | `dbhostname` | Value of `HostName` database property | `host` | | `dbname` | Value of `DatabaseName` database property | `string` | | `dbloginname` | Value of `LoginName`  database property | `string` | | `dburldefault` | A computed value based on the database properties | `string` | | `dburl` | Value of `DBURL` database property | `string` | > **Note:** The dburldefault is used as the default value for the database URL. So if you don’t edit the DBURL, it should be identical to dburl. ### Sample XML response `/api/setup.xml`  ```xml false false false false false mail.example.org 25 false false dev unlimited unlimited unlimited localhost http 8080 localhost MySQL sample-db pageseeder pageseeder jdbc:mysql://sample-db/pageseeder jdbc:mysql://sample-db/pageseeder ``` ### Sample JSON response `/api/setup.json`  > **Note:** In JSON, values are returned as strings, unless they are `boolean` values that are not global properties. For example, port numbers are returned as strings. ```json { "licenseexpired":false, "loginrequired":false, "productkeyinvalid":false, "organizationdisabled":false, "organizationerror":false, "smtpserveraddress":"mail.example.org", "smtpserverport":"25", "smtpserverusername":"", "smtpserverpassword":"", "smtpserverssl":"false", "smtpserverstarttls":"false", "productkey":"dev", "projects":"unlimited", "groups":"unlimited", "members":"unlimited", "licenseexpires":"", "websiteaddress":"localhost", "websitescheme":"http", "websiteport":"8080", "emaildomain":"localhost", "dbtype":"MySQL", "dbhostname":"sample-db", "dbname":"pageseeder", "dbloginname":"pageseeder", "dburldefault":"jdbc:mysql://sample-db/pageseeder", "dburl":"jdbc:mysql://sample-db/pageseeder" } ``` ## Error handling | HTTP status code | Error condition | | --- | --- | | **400** | One or more parameters is missing | | **400** | The database login password is not strong (create database only) | | **400** | The invalid administrator email address (creating tables only) | | **400** | Administrator password cannot be empty (creating tables only) | | **400** | Administrator password is too weak (creating tables only) | | **400** | Administrator password is the same as the username (creating tables only) | | **400** | Administrator username is invalid (creating tables only) | | **400** | SMTP server port is invalid | | **400** | PageSeeder cannot connect to mail server | | **400** | Invalid database, cannot retrieve database version (updating database only) | | **400** | Database version does not match current version  (updating database only) | | **401** | If PageSeeder is already configured and the user is not authenticated | | **403** | If PageSeeder is already configured and the user is not an administrator |