# Create a knowledge page

Launch stage: Beta

`POST /api/2.0/knowledge/pages`

Create a knowledge page. For REST, send Page fields directly as the JSON
 request body. Retrying a draft create can create another page.
 When page permissions are enforced, creating a published page or assigning
 another owner requires Page Manager or Domain Admin permissions on the domain,
 including inherited grants. Creating your own draft requires neither grant.

 Errors: `INVALID_PARAMETER_VALUE` (missing `page`/`domain` or field validation),
 `NOT_FOUND` (the referenced `domain` does not exist), `ALREADY_EXISTS` (a
 published page with the same `domain` and `display_name` already exists),
 `PERMISSION_DENIED` (insufficient permissions), `RESOURCE_EXHAUSTED`
 (rate limited), `INTERNAL_ERROR` (unexpected failure).

API scopes: knowledge

## Query parameters

- `request_id` (string, optional)
  Optional UUIDv4 scoped to the account and caller. Retries return the current
   page without applying retry payload changes. Every retry must pass request
   validation and current create permissions, plus view permission on the returned
   page. Deletion releases the token; later retries may create a new page.

## Request body

The page to create. `domain` and `display_name` are required; the server
 assigns `name`, `create_time`, and `update_time`. Other fields follow the
 defaults and format requirements documented on Page.
- `name` (string, optional, ID, Immutable)
  Resource name in the form `pages/{page_id}`, where `page_id` is a
   server-generated UUID. Omit on create; required to identify the page on
   update. Get and Delete also address pages by this full resource name.
- `domain` (string, optional)
  Resource name of the domain this page belongs to; format `domains/{domain_id}`.
   Required on create. Use the full resource name rather than a bare domain ID.
   The domain is fixed after creation; updating it is not supported.
- `display_name` (string, optional)
  Human-readable title, 1 to 200 characters.
   Required on create and when selected by `update_mask`.
   Published titles must be unique within the domain.
- `body` (string, optional)
  Page body as Markdown text. An update replaces the entire body when
   `body` is selected by `update_mask`.
- `synonyms` (array of string, optional)
  Alternate names or abbreviations. Accepts at most 50 entries, each 1 to
   200 characters. Values are trimmed, deduplicated, and sorted.
   An update replaces the entire list when `synonyms` is selected by
   `update_mask`; an empty list clears it.
- `description` (string, optional)
  Short description of the page. An update replaces the description when
   `description` is selected by `update_mask`.
- `state` (string, optional)
  Lifecycle state. Omitting it on create defaults to `DRAFT`. Set `PUBLISHED`
   to publish or `DRAFT` to unpublish. An update selecting `state` in
   `update_mask` must explicitly supply `DRAFT` or `PUBLISHED`.
  Possible values:
  - `DRAFT`
  - `PUBLISHED`
- `owner_ids` (array of string, optional)
  Decimal principal ID strings for the page's single owner: a user, group,
   or service principal. Use principal IDs rather than email addresses or
   service-principal application UUIDs. On create, an omitted or empty list
   defaults to the caller; at most one ID may be supplied. An update selecting
   `owner_ids` in `update_mask` must supply exactly one ID to replace the owner.

## Returns

Returns the Page object.

## Response

```json
{
  "name": "string",
  "domain": "string",
  "display_name": "string",
  "body": "string",
  "synonyms": [
    "string"
  ],
  "description": "string",
  "state": "DRAFT",
  "create_time": "string",
  "update_time": "string",
  "owner_ids": [
    "string"
  ]
}
```