<!-- https://developers.silktide.com/v1/governance/websites/create-website | Governance / Websites -->

# Create a website

`POST /v1/websites`

Creates a website and, unless you say otherwise, starts testing it straight
away. The response is the new website, as
[Get a website](https://developers.silktide.com/v1/governance/websites/get-website.md) returns it.

The pages and documents you give it come out of the account's balance, so
check [Get the account's balance](https://developers.silktide.com/v1/platform/balances/get-account-balance.md)
first. Always send `maxPages` and `maxDocuments`: left out, Silktide picks an
allocation for you.

To configure a website before its first test, send `runNow: false` and
`isReady: false`. It stays in `setup` until you
[test it](https://developers.silktide.com/v1/governance/websites/test-website.md).

`metaValues` goes inside `website`. Older documentation showed it beside
`website`, where it is ignored.

A missing `name` or `homeUrl` currently returns `500` rather than a `400`
naming the field.

## Request

### Body

- `website` (object, required): The website.
  - `name` (string, required, 1 to 200 characters): Its name. Plain text: no markup or control characters.
  - `homeUrl` (string, required): Its home page, as a full URL. Silktide tests everything under it.
  - `maxPages` (integer, optional, at least 1): The most pages to test. Must fit in the account's balance. Always send it.
  - `maxDocuments` (integer, optional): The most documents (PDFs) to test. Must fit in the account's balance. Always send it.
  - `runNow` (boolean, optional): Start its first test now. Defaults to `true`.
  - `isReady` (boolean, optional): With `runNow: false`, `false` leaves it in `setup` so you can finish configuring it first. Defaults to `true`.
  - `metaValues` (map of strings, optional): Metadata for the whole website, by metadata property name. Names the account has no property for are ignored.
- `schedule` (object, optional): When to retest it. Replaces the whole schedule: any key left out takes its default.
  - `scheduleInterval` (string, optional): The unit to retest in. Defaults to empty, which is no schedule. One of: `second`, `minute`, `hour`, `day`, `week`, `month`, `year`.
  - `schedulePeriod` (integer, optional, at least 1): How many intervals apart tests are. Defaults to `1`.
  - `scheduleFromDate` (integer, optional): When the schedule counts from. Defaults to now.
  - `schedulePreset` (string, optional): A named schedule, used instead of the interval and period: `five-daily`, `weekly`, `monthly`, or `none` for no schedule. One of: `none`, `five-daily`, `weekly`, `monthly`.
  - `isActive` (boolean, optional): Whether scheduled tests run. Defaults to `true`.
- `options` (object, optional): Settings to change. Ones left out keep their value.
  - `website.allowFragmentPaths` (boolean, optional): Experimental. Crawl paths with fragments, such as hashbangs.
  - `website.allowedHttpCodes` (list of integers, optional): HTTP codes to accept besides 2xx and 3xx, which are always accepted.
  - `website.authType` (string, optional): How Silktide signs in to pages that need it.
  - `website.benchmarkId` (string, optional): The Silktide Benchmark to grade against. Empty for none.
  - `website.benchmarkPercentile` (integer, optional): The percentile to read from the benchmark.
  - `website.brokenLinkMaxRedirects` (integer, optional): How many redirects a link may take before it counts as broken.
  - `website.brokenLinkPropulsionFallback` (boolean, optional): Confirm broken links in a real browser. Slower but more reliable.
  - `website.brokenLinkTimeout` (integer, optional): Seconds to wait before a link counts as broken.
  - `website.clickSelector` (string, optional): A CSS selector Silktide clicks on each page before testing it.
  - `website.disableAnalytics` (boolean, optional): Block the website's analytics scripts while testing, so tests do not count as visits.
  - `website.disableFirstTimeVisit` (boolean, optional): Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.
  - `website.disableLinkDiscovery` (boolean, optional): Test only the URLs you give, and follow no links.
  - `website.disableScrollDown` (boolean, optional): Do not scroll each page to the bottom and back while testing.
  - `website.disableStealth` (boolean, optional): Let websites detect that Silktide's browser is automated.
  - `website.enableAnimation` (boolean, optional): Let pages animate. Silktide stops animation by default.
  - `website.exclude3rdPartyPluginIssues` (boolean, optional): Ignore issues inside common third-party plugins, such as embedded maps.
  - `website.excludeQueryParams` (list of strings, optional): Query parameters to remove from URLs, so pages that differ only by them count once.
  - `website.ignoreAutomaticSitemaps` (boolean, optional): Do not use the sitemaps Silktide finds on its own.
  - `website.inspectorCss` (string, optional): CSS added to pages when they are shown in the Inspector.
  - `website.languages` (list of strings, optional): Language codes, such as `en-US`, that every page is in. Always present.
  - `website.maxConnections` (integer, optional): How many pages Silktide may load at once.
  - `website.normalizeUrlPath` (boolean, optional): Lowercase URL paths, for websites that mix case.
  - `website.optionalLanguages` (list of strings, optional): Language codes a page might be in. Silktide detects them per page, which slows testing.
  - `website.pageWait` (number, optional): Seconds to wait after a page loads before testing it.
  - `website.proxyHost` (string, optional): A proxy server to test through.
  - `website.proxyPort` (integer, optional): The proxy server's port.
  - `website.proxyPreset` (string, optional): One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.
  - `website.proxyUsername` (string, optional): The proxy server's username.
  - `website.readabilityFormula` (string, optional): The readability formula, such as `smog`.
  - `website.readabilityThreshold` (number, optional): The readability score pages should stay within.
  - `website.reportLanguage` (string, optional): The language AI reports about the website are written in. Empty for the account's language.
  - `website.timeout` (integer, optional): Seconds to wait for a page to load before giving up.
  - `website.trustPageDeclaredLanguage` (boolean, optional): Believe the language a page declares rather than detecting it.
  - `website.userAgentSuffix` (string, optional): Text added to the end of Silktide's browser user agent.
  - `website.username` (string, optional): The username Silktide signs in to pages with.
  - `website.aiEnabled` (boolean, optional): Whether Silktide's AI may work on this website.
  - `website.password` (string, optional): The password Silktide signs in to pages with. Write-only: reads say only whether one is set. Leave it out to keep the saved one; an empty string removes it.
  - `website.proxyPassword` (string, optional): The proxy server's password. Write-only, like `website.password`.
- `tagIds` (list of strings, optional): The tags for the whole website (section `0`). Replaces its tags; `[]` removes them all.
- `governanceAiOptimizer` (boolean, optional): Whether to give it one of the account's Governance AI optimizers. Left out, it takes a free one unless it cannot use AI.

## Response

Status `200`.

- `website` (object, required): The website.
  - `websiteId` (integer, required, at least 1): The website.
  - `name` (string, required): Its name.
  - `homeUrl` (string, required): Its home page.
  - `status` (string, required): `installing` while Silktide creates it, `setup` before it goes live, `live` once it is tested. One of: `installing`, `setup`, `live`.
  - `maxPages` (integer, required): The most pages Silktide will test.
  - `maxDocuments` (integer, required): The most documents (PDFs) Silktide will test.
  - `created` (integer, required): When it was created.
  - `lastTested` (integer, required): When its last test finished. `0` if it has never been tested.
  - `propertyId` (integer, required): The Analytics property linked to the website. `0` when it has none.
- `permissions` (object, required): Who may do what with the website.
  - `components` (list of objects, required): The permissions a website has.
    - `permissionId` (string, required): The permission, such as `Website-WebsiteRead`.
    - `componentType` (string, required): What can be given it. `assignees` for users and roles.
    - `label` (string, required): Its name.
    - `description` (string, required, can be null): What it allows. Null for some permissions.
    - `inheritedPermissionIds` (list of strings, required): Permissions that include this one: anyone with those has this too.
    - `models` (list of any JSON, required): Reserved. Empty for website permissions.
  - `componentValues` (map of list of strings, required): Who was given each permission on this website directly, as assignee ids (`u:` users, `g:` roles).
  - `fixedValues` (map of list of strings, required): Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here.
- `schedule` (object, required): When it is retested.
  - `scheduleInterval` (string, required): The unit it is retested in. Empty when it is not retested on a schedule. One of: `second`, `minute`, `hour`, `day`, `week`, `month`, `year`.
  - `schedulePeriod` (integer, required): How many `scheduleInterval`s apart tests are.
  - `scheduleFromDate` (integer, required): When the schedule counts from.
  - `schedulePreset` (string, required): A named schedule (`none`, `five-daily`, `weekly` or `monthly`), or empty when the interval and period were set directly.
  - `isActive` (boolean, required): Whether scheduled tests run.
- `options` (object, required): Its settings, by name.
  - `website.allowFragmentPaths` (boolean, optional): Experimental. Crawl paths with fragments, such as hashbangs.
  - `website.allowedHttpCodes` (list of integers, optional): HTTP codes to accept besides 2xx and 3xx, which are always accepted.
  - `website.authType` (string, optional): How Silktide signs in to pages that need it.
  - `website.benchmarkId` (string, optional): The Silktide Benchmark to grade against. Empty for none.
  - `website.benchmarkPercentile` (integer, optional): The percentile to read from the benchmark.
  - `website.brokenLinkMaxRedirects` (integer, optional): How many redirects a link may take before it counts as broken.
  - `website.brokenLinkPropulsionFallback` (boolean, optional): Confirm broken links in a real browser. Slower but more reliable.
  - `website.brokenLinkTimeout` (integer, optional): Seconds to wait before a link counts as broken.
  - `website.clickSelector` (string, optional): A CSS selector Silktide clicks on each page before testing it.
  - `website.disableAnalytics` (boolean, optional): Block the website's analytics scripts while testing, so tests do not count as visits.
  - `website.disableFirstTimeVisit` (boolean, optional): Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.
  - `website.disableLinkDiscovery` (boolean, optional): Test only the URLs you give, and follow no links.
  - `website.disableScrollDown` (boolean, optional): Do not scroll each page to the bottom and back while testing.
  - `website.disableStealth` (boolean, optional): Let websites detect that Silktide's browser is automated.
  - `website.enableAnimation` (boolean, optional): Let pages animate. Silktide stops animation by default.
  - `website.exclude3rdPartyPluginIssues` (boolean, optional): Ignore issues inside common third-party plugins, such as embedded maps.
  - `website.excludeQueryParams` (list of strings, optional): Query parameters to remove from URLs, so pages that differ only by them count once.
  - `website.ignoreAutomaticSitemaps` (boolean, optional): Do not use the sitemaps Silktide finds on its own.
  - `website.inspectorCss` (string, optional): CSS added to pages when they are shown in the Inspector.
  - `website.languages` (list of strings, required): Language codes, such as `en-US`, that every page is in. Always present.
  - `website.maxConnections` (integer, optional): How many pages Silktide may load at once.
  - `website.normalizeUrlPath` (boolean, optional): Lowercase URL paths, for websites that mix case.
  - `website.optionalLanguages` (list of strings, optional): Language codes a page might be in. Silktide detects them per page, which slows testing.
  - `website.pageWait` (number, optional): Seconds to wait after a page loads before testing it.
  - `website.proxyHost` (string, optional): A proxy server to test through.
  - `website.proxyPort` (integer, optional): The proxy server's port.
  - `website.proxyPreset` (string, optional): One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.
  - `website.proxyUsername` (string, optional): The proxy server's username.
  - `website.readabilityFormula` (string, optional): The readability formula, such as `smog`.
  - `website.readabilityThreshold` (number, optional): The readability score pages should stay within.
  - `website.reportLanguage` (string, optional): The language AI reports about the website are written in. Empty for the account's language.
  - `website.timeout` (integer, optional): Seconds to wait for a page to load before giving up.
  - `website.trustPageDeclaredLanguage` (boolean, optional): Believe the language a page declares rather than detecting it.
  - `website.userAgentSuffix` (string, optional): Text added to the end of Silktide's browser user agent.
  - `website.username` (string, optional): The username Silktide signs in to pages with.
  - `website.aiEnabled` (boolean, optional): Whether Silktide's AI may work on this website.
  - `website.passwordSet` (boolean, required): Whether a sign-in password is saved. Always present. Read-only: sending it changes nothing.
  - `website.proxyPasswordSet` (boolean, required): Whether a proxy password is saved. Always present. Read-only, like `website.passwordSet`.
- `tagIds` (list of strings, required): The ids of the tags on the whole website (section `0`).
- `governanceAiOptimizer` (boolean, required): Whether the website holds one of the account's Governance AI optimizers.
- `governanceAiOptimizerAvailable` (boolean, required): Whether it could be given one now, counting one its own recent reports still hold.
- `reportLanguage` (string, required): The language its AI reports are written in: its own setting, or the account's when unset.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 403 | `AccessDenied` | The account cannot add another website, or `maxPages` or `maxDocuments` is more than its balance has left. |
| 400 | `InvalidRequest` | The name contains markup or control characters, `website.reportLanguage` is not a language Silktide writes reports in, or `tagIds` adds an id that is not one of the account's `section` tags. `properties.field` names it. |
| 500 | `Runtime` | `name` or `homeUrl` is missing. |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: any user of the account
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: uses the account's allowance
- Stability: stable, since 1.0.0

## Example: A website tested weekly, starting now

```bash
curl -X POST "https://api.eu.silktide.com/v1/websites" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "website": {
    "name": "Fake University",
    "homeUrl": "https://fake-university.example/",
    "maxPages": 100,
    "maxDocuments": 100,
    "metaValues": {
      "author": "Joe Bloggs"
    }
  },
  "schedule": {
    "schedulePreset": "weekly"
  },
  "options": {
    "website.benchmarkId": "fortune-500-usa",
    "website.benchmarkPercentile": 90
  },
  "tagIds": [
    "pre-production"
  ]
}'
```

Response:

```json
{
  "website": {
    "websiteId": 6,
    "name": "Fake University",
    "homeUrl": "https://fake-university.example/",
    "status": "live",
    "maxPages": 100,
    "maxDocuments": 100,
    "created": 1793736881,
    "lastTested": 0,
    "propertyId": 0
  },
  "permissions": {
    "components": [],
    "componentValues": {},
    "fixedValues": {}
  },
  "schedule": {
    "scheduleInterval": "week",
    "schedulePeriod": 1,
    "scheduleFromDate": 1793736881,
    "schedulePreset": "weekly",
    "isActive": true
  },
  "options": {
    "website.languages": [
      "en-US"
    ],
    "website.benchmarkId": "fortune-500-usa",
    "website.benchmarkPercentile": 90,
    "website.passwordSet": false,
    "website.proxyPasswordSet": false
  },
  "tagIds": [
    "pre-production"
  ],
  "governanceAiOptimizer": true,
  "governanceAiOptimizerAvailable": true,
  "reportLanguage": "en-US"
}
```