Admin GraphQL Schema

This document provides an overview of the GraphQL schema, which defines the structure of the API and the the available queries, mutations, object types, input types, and scalar types.

Query

The Query type is the entry point for all read operations in the GraphQL schema and provides access to read operations in the schema. This section lists the fields that you can use to retrieve data, such as getting all models or a specific model by ID.

Fields

models: [ModelType!]!: Retrieves a list of all models.
model(id: String!): ModelType: Retrieves a specific model by its ID.
id: String!: Retrieves the ID of the current object.
settings: JSONObject!: Retrieves the settings of the current object.
downloadClone(contentQuery: ContentQuery): SpaceType!: Downloads a clone of a space based on the provided content query.

The example below shows querying pages with pagination:

query { page(limit: 10, offset: 20) { id name fields { name type value } } }

See the Query assets section in Assets API for examples of fetching and filtering assets.

Mutation

The Mutation type is the entry point for all write operations in the GraphQL schema. This section lists the fields that you can use to modify data, such as creating, updating, or deleting models, as well as managing Spaces, authentication providers, and plugins.

Fields

addModel(body: JSONObject!): ModelType: Creates a new model with the provided data.
updateModel(body: UpdateModelInput!): ModelType: Updates an existing model with the provided data.
deleteModel(id: String!): ModelType: Deletes a model with the specified ID.
createSpace(settings: JSONObject!): JSONObject!: Creates a new space with the provided settings. Requires a private key of the root organization in the authentication headers and returns the private key of the newly created space.
addSAMLProvider(settings: SAMLProviderSettings!): Void!: Adds a SAML provider to the space settings.
addOIDCProvider(settings: OIDCProviderSettings!): Void!: Adds an OIDC provider to the space settings.
deleteAsset(id: String!): Void!: Deletes an asset with the specified ID. See the Delete assets section of Assets API for more information.
deleteAuthProvider: Void!: Deletes an authentication provider from the space settings.
generateEmbedToken(claims: EmbedTokenClaims!): EmbedTokenResponse!: Generates a temporary token to verify the ability to embed content within the specified domain.
archiveSpace: Void!: Archives a space using its private key.
updatePlugins(loadPlugins: [String!]!): Void!: Updates the list of plugins for a space using its private key.

Below is an example of a mutation with addModel for an announcement bar.

mutation { addModel(body: { name: "Announcement Bar" kind: "component" fields: [ { name: "Headline" type: "text" required: true } ] }) { id name kind fields { name type required } } }

Objects

The schema defines several object types that represent the data structures used in the API. Each object type has a set of fields with their respective data types. This section lists the main object types.

ModelType

Represents a model with various fields such as ID, name, kind, URL, text, dates, booleans, webhooks, and more.

Fields

id: ID: The unique identifier of the model.
name: String!: The name of the model.
kind: String!: The kind or type of the model.
examplePageUrl: String: The URL of an example page for the model.
helperText: String: Helper text or description for the model.
lastUpdatedBy: String: The user who last updated the model.
hidden: Boolean: Indicates whether the model is hidden.
archived: Boolean: Indicates whether the model is archived.
individualEmbed: Boolean: Indicates whether the model supports individual embedding.
componentsOnlyMode: Boolean: Indicates whether the model is in components-only mode.
publicReadable: Boolean: Indicates whether the model is publicly readable.
webhooks: [Webhook!]: A list of associated webhooks for the model.
fields: [JSONObject!]: Custom fields associated with the model.
requiredTargets: [String!]: Required targets for the model.

Below is an example of using ModelType to query a specific model by its ID:

query { modelType(id: "abc123") { id name kind } }

ModelWithContent

Represents a model with content, extending all fields from ModelType.

Fields

Extends all fields from ModelType, no additional fields

SpaceType

Represents a space with settings, metadata, and associated models.

Fields

settings: JSONObject!: The settings of the space.
meta: JSONObject!: Metadata associated with the space.
models: [ModelWithContent!]!: A list of models with content associated with the space.

Webhook

Represents a webhook definition with fields for payload settings, URL, and custom headers.

Fields

disablePayload: Boolean: Indicates whether the payload should be disabled for the webhook. Some webhooks have payload size limits, and disabling the payload sends only the POST request without the actual data.
url: String!: The URL where the webhook will send HTTP POST requests with fields containing the new and previous values.
customHeaders: [Header!]: Custom headers that can be optionally sent with the webhook calls.

Header

Represents a custom header for webhooks with name and value fields.

Fields

name: String!: The name of the header.
value: String!: The value of the header.

QueryType

Represents a query type with fields for property, operator, and value.

Fields

property: String: The property to query.
operator: String!: The operator for the query.
value: JSON!: The value to compare against in the query.

EmbedTokenResponse

Represents the response for an embed token request, including the token and expiration date.

Fields

token: String!: The generated embed token.
expires: Float!: The expiration date of the token, typically one hour from the time of request.

Inputs

This section describes the input types you can use in mutation operations. Input types define the structure of the data that can be sent to the API when performing a mutation.

UpdateModelInput

Used to update a model with the specified ID and data.

Fields

id: String!: The ID of the model to update.
data: JSONObject!: The updated data for the model.

SAMLProviderSettings

Represents the settings for a SAML authentication provider, including display name, identity provider entity ID, SSO URL, X.509 certificate, and service provider entity ID.

Fields

displayName: String!: The user-friendly display name for the SAML provider configuration.
idpEntityId: String!: The entity identifier of the SAML identity provider.
ssoURL: String!: The single sign-on URL of the SAML identity provider. This must be a valid URL.
x509Cert: String!: The X.509 certificate used for token signing by the SAML identity provider.
rpEntityId: String: The entity identifier of the service provider (relying party). Defaults to https://www.builder.io and should not be changed unless required by the identity provider.

OIDCProviderSettings

Represents the settings for an OIDC authentication provider, including display name, client ID, and issuer URL.

Fields

displayName: String!: The user-friendly display name for the OIDC provider configuration.
clientId: String!: The client ID used to validate the audience of the OIDC provider's ID token.
issuer: String!: The issuer URL of the OIDC provider. This is used to match the issuer of the ID token and to determine the OIDC discovery document location (typically at /.well-known/openid-configuration).

EmbedTokenClaims

Represents the claims for generating an embed token, including the space ID and domain.

Fields

spaceId: String!: The public key of the space to embed.
domain: String!: The domain where the space will be embedded. This should be a full URL, for example, https://mybuilder.example.com.

ContentQuery

Represents a query for retrieving content with fields for pagination, filtering, targeting, options, and sorting.

Fields

limit: Float: The maximum number of results to return. For example, limit: 10, offset: 10 retrieves 10 results starting from the 11th result.
offset: Float: The number of results to skip before returning the results. For example, limit: 10, offset: 10 retrieves 10 results starting from the 11th result.
query: JSONObject: A MongoDB-style query object for filtering the results. For example, query: { id: "abc123", data: { customNumberField: { $lt: 100 } } } retrieves results where the id is "abc123" and the customNumberField is less than 100.
target: JSONObject: An object representing targeting information. For example, target: { urlPath: "/foobar", device: "mobile" } retrieves content targeted to the URL path /foobar on mobile devices.
options: JSONObject: Additional options for the API request. For example, options: { includeUnpublished: true } includes unpublished content in the results.
sort: JSONObject: An object specifying the sorting order of the results. For example, sort: { createdDate: -1 } sorts the results by the createdDate field in descending order.

See the Use variables for dynamic queries section in Assets API for more information.

Targeting and locale input types

The following input types define the structure used when configuring targeting attributes, locales, locale groups, and responsive breakpoints in a Builder Space.

TargetingAttributeInput

Represents a single custom targeting attribute key-value pair.

Field	Type	Required	Description
`key`	`String`	Yes	Unique identifier for the attribute.
`schema`	`TargetingAttributeSchemaInput`	Yes	Schema definition for the attribute.

TargetingAttributeSchemaInput

Defines the schema for a targeting attribute value.

Field	Type	Required	Description
`type`	`String`	Yes	Data type of the attribute; for example, `"string"`.
`enum`	`[String]`	No	Allowed values for the attribute.
`descriptions`	`[LocaleDescriptionInput]`	No	Per-locale display descriptions for enum values.
`groups`	`JSONObject`	No	Arbitrary grouping metadata for the attribute values.

LocaleDescriptionInput

Describes a single locale entry with optional display metadata.

Field	Type	Required	Description
`name`	`String`	Yes	BCP 47 locale tag; for example,`"en-US"`, `"fr-FR"`.
`description`	`String`	No	Human-readable label for the locale.
`groups`	`[String]`	No	Locale group names this locale belongs to.

LocaleGroupEntryInput

Represents a single locale group and its default locale.

Field	Type	Required	Description
`name`	`String`	Yes	Unique name for the locale group; for example, `"emea"`*.
`defaultLocale`	`String`	Yes	Standard language and region code (BCP 47), such as `en-US` or `fr-FR`, used as the group default.

* EMEA stands for Europe, Middle East, and Africa. Other common business abbreviations include AMER for Americas, and APAC for Asia-Pacific.

BreakpointsInput

Defines responsive breakpoint values in pixels. All values must be integers with at least 2 pixels of spacing between them.

Field	Type	Required	Description
`xsmall`	`Int`	No	Upper bound in px for the extra-small viewport.
`small`	`Int`	Yes	Upper bound in pixels for the small viewport.
`medium`	`Int`	Yes	Upper bound in pixels for the medium viewport.

Scalars

Scalars are the primitive data types in the schema. Use these types to define the fields of objects and inputs.

ID: Represents a unique identifier, often used to retrieve an object or as a cache key. It is serialized as a string but is not intended to be human-readable.
Float: Represents signed double-precision fractional values as specified by IEEE 754.
Int: Represents non-fractional signed whole numeric values between -(2^31) and 2^31 - 1.
JSON: Represents JSON values as specified by ECMA-404.
JSONObject: Represents JSON objects — also known as dictionaries, maps, or associative arrays — as specified by ECMA-404.
String: Represents textual data as UTF-8 character sequences.
Boolean: Represents true or false values.
Void: Represents NULL values.

Was this article helpful?