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

# List websites and their sections

`GET /v1/websites`

Returns every website the API key's user can see, one entry per section. Each
website has a section `0`, which is the whole website, and any sections made
within it have ids of their own. A `subsiteId` names one of them, as
`{websiteId}-{sectionId}`.

Use the `websiteId` with the other Websites operations, and the `subsiteId`
with results queries that take a section.

`tags` is only sent when you ask for it with `includeTags=1`, and even then it
is left out, rather than sent empty, for a section with no tags. Treat a
missing `tags` as none.

## Request

### Query parameters

- `searchText` (string, optional): Only sections whose name or home page contains this.
- `tagIds` (list of strings, optional): Only sections with at least one of these tags. Send as `tagIds[]=…`.
- `includeTags` (string, optional): `1` to include each section's tags. Any value other than `0` or empty counts as `1`. One of: `0`, `1`.
- `orderBy` (string, optional): The order. Defaults to `recentlyViewed`. One of: `name`, `recentlyViewed`, `recentlyCreated`, `recentlyTested`, `leastRecentlyTested`.

## Response

Status `200`.

- `websites` (list of objects, required): One entry per section the API key's user can see. Section `0` of each website is the whole website.
  - `subsiteId` (string, required, `{websiteId}-{sectionId}`): The website and section together, as `{websiteId}-{sectionId}`.
  - `websiteId` (integer, required, at least 1): The website.
  - `sectionId` (integer, required): The section within the website. `0` is the whole website.
  - `name` (string, required): The section's name. For section `0`, the website's name.
  - `homeUrl` (string, required): The section's home page. Can be empty.
  - `created` (integer, required): When the section was created.
  - `websiteName` (string, required): The website's name.
  - `websiteStatus` (string, required): `installing` while Silktide creates it, `setup` while it is being configured before it goes live, `live` once it is tested. One of: `installing`, `setup`, `live`.
  - `numPages` (integer, required): Pages Silktide has found in the section.
  - `numDocuments` (integer, required): Documents (PDFs) Silktide has found in the section.
  - `thumbnailUrl` (string, required): A small screenshot of the section. Empty until one exists.
  - `lastViewed` (integer, optional): When the API key's user last viewed the section. `0` if never. Only when `orderBy` is `recentlyViewed`, the default; absent with any other order.
  - `tags` (list of objects, optional): The section's tags. Only with `includeTags`, and absent when the section has none.
    - `tagId` (string, required): The tag's id.
    - `entityType` (string, required): What the tag is on. `section` for a website or section.
    - `entityId` (string, required): The `subsiteId` of the section it is on.
    - `label` (string, required): The tag's name.
    - `color` (string, required): Its color, as a hex code such as `#EBA52C`.
    - `tagGroup` (string, required): The group it belongs to. Empty when it has none.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 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: free
- Stability: stable, since 1.0.0

## Example: Two websites, with tags

```bash
curl "https://api.eu.silktide.com/v1/websites?includeTags=1&orderBy=name" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
```

Response:

```json
{
  "websites": [
    {
      "subsiteId": "2-0",
      "websiteId": 2,
      "sectionId": 0,
      "name": "Example",
      "homeUrl": "https://example.com/",
      "created": 1790216529,
      "websiteName": "Example",
      "websiteStatus": "live",
      "numPages": 812,
      "numDocuments": 40,
      "thumbnailUrl": "https://example-bucket.s3.amazonaws.com/websites/2/screenshots/desktop-thumb.webp",
      "tags": [
        {
          "tagId": "marketing",
          "entityType": "section",
          "entityId": "2-0",
          "label": "Marketing",
          "color": "#EBA52C",
          "tagGroup": ""
        }
      ]
    },
    {
      "subsiteId": "2-1",
      "websiteId": 2,
      "sectionId": 1,
      "name": "Blog",
      "homeUrl": "https://example.com/blog/",
      "created": 1790216600,
      "websiteName": "Example",
      "websiteStatus": "live",
      "numPages": 120,
      "numDocuments": 0,
      "thumbnailUrl": ""
    }
  ]
}
```