Skip to main content

Page

View as Markdown

A knowledge page: a domain-scoped governance document describing a concept or term in the account.

Page object​

A knowledge page: a domain-scoped governance document describing a concept or term in the account.

namestringBetaIDImmutable

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.

domainstringBeta

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_namestringBeta

Human-readable title, 1 to 200 characters. Required on create and when selected by update_mask. Published titles must be unique within the domain.

bodystringBeta

Page body as Markdown text. An update replaces the entire body when body is selected by update_mask.

synonymsarray of stringBeta

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.

descriptionstringBeta

Short description of the page. An update replaces the description when description is selected by update_mask.

statestringBeta

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.

Values:

  • DRAFT
  • PUBLISHED
create_timestringBetaOutput only

Server-assigned creation time, formatted as an RFC 3339 timestamp in JSON.

update_timestringBetaOutput only

Server-assigned last-update time, formatted as an RFC 3339 timestamp in JSON.

owner_idsarray of stringBeta

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.

Get a knowledge page Beta​

GET /api/2.0/knowledge/{name=pages/*}

Get a knowledge page by resource name.

Returns NOT_FOUND if no page with the given name exists.

API scopes: knowledge

Parameters​

namestringRequiredpath

Resource name of the page to retrieve. Format: pages/{page_id}

Response​

Returns the Page object.

List knowledge pages Beta​

GET /api/2.0/knowledge/pages

List visible knowledge pages in the account, optionally narrowed by domain and state. With a domain filter, the caller must administer that domain, including through inherited grants. Without a domain filter, including when filtering only by state, account-wide Manage Discover or Account Admin permission is required. List returns page metadata.

API scopes: knowledge

Parameters​

page_sizeint32query

Maximum number of pages to return, from 1 to 100. Defaults to 50 when omitted. The server may return fewer.

page_tokenstringquery

Opaque next_page_token from a previous ListPages response. Omit on the first request; pass it unchanged and keep the same filter when continuing.

filterstringquery

Filter clauses with double-quoted values, joined by uppercase AND. Each field may appear once:

  • domain = "domains/{domain_id}" includes that domain and its subdomains.
  • state = "DRAFT" or state = "PUBLISHED" matches that state exactly. For example: domain = "domains/{domain_id}" AND state = "PUBLISHED". Other fields and operators are not supported. An omitted or blank filter lists visible pages across the account, subject to ListPages permissions.

Response​

Returns a list of Page objects.

Create a knowledge page 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

Parameters​

request_idstringquery

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.

namestringIDImmutable

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.

domainstring

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_namestring

Human-readable title, 1 to 200 characters. Required on create and when selected by update_mask. Published titles must be unique within the domain.

bodystring

Page body as Markdown text. An update replaces the entire body when body is selected by update_mask.

synonymsarray of string

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.

descriptionstring

Short description of the page. An update replaces the description when description is selected by update_mask.

statestring

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.

Values:

  • DRAFT
  • PUBLISHED
owner_idsarray of string

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.

Response​

Returns the Page object.

Update a knowledge page Beta​

PATCH /api/2.0/knowledge/{name=pages/*}

Update an existing knowledge page. For REST, send Page fields directly as the JSON body and supply update_mask as a query parameter. The resource name identifies the page; omitted mask fields retain their stored values.

Errors: INVALID_PARAMETER_VALUE (field validation), NOT_FOUND (the page does not exist), ALREADY_EXISTS (a rename would collide with another published page), RESOURCE_EXHAUSTED, ABORTED, INTERNAL_ERROR.

API scopes: knowledge

Parameters​

namestringRequiredIDImmutablepath

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.

update_maskstringRequiredquery

Nonempty set of Page fields to update. Supported paths are display_name, body, synonyms, description, state, and owner_ids, without a page. prefix. Wildcards, domain, and server-assigned fields are not supported. In REST requests, pass a comma-separated query parameter, for example update_mask=display_name,body. There is no implicit update of all fields.

Request body​

The page to update. name is required in the form pages/{page_id}. Only fields selected by update_mask are written.

domainstring

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_namestring

Human-readable title, 1 to 200 characters. Required on create and when selected by update_mask. Published titles must be unique within the domain.

bodystring

Page body as Markdown text. An update replaces the entire body when body is selected by update_mask.

synonymsarray of string

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.

descriptionstring

Short description of the page. An update replaces the description when description is selected by update_mask.

statestring

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.

Values:

  • DRAFT
  • PUBLISHED
owner_idsarray of string

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.

Response​

Returns the Page object.

Delete a knowledge page Beta​

DELETE /api/2.0/knowledge/{name=pages/*}

Delete a knowledge page by resource name.

Returns NOT_FOUND if no page with the given name exists.

API scopes: knowledge

Parameters​

namestringRequiredpath

Resource name of the page to delete. Format: pages/{page_id}