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.
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.
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
}
}
}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.
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.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
}
}
}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.
Represents a model with various fields such as ID, name, kind, URL, text, dates, booleans, webhooks, and more.
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
}
}Represents a model with content, extending all fields from ModelType.
Extends all fields from ModelType, no additional fields
Represents a space with settings, metadata, and associated models.
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.
Represents a webhook definition with fields for payload settings, URL, and custom headers.
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.
Represents a custom header for webhooks with name and value fields.
name: String!: The name of the header.value: String!: The value of the header.
Represents a query type with fields for property, operator, and value.
property: String: The property to query.operator: String!: The operator for the query.value: JSON!: The value to compare against in the query.
Represents the response for an embed token request, including the token and expiration date.
token: String!: The generated embed token.expires: Float!: The expiration date of the token, typically one hour from the time of request.
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.
Used to update a model with the specified ID and data.
id: String!: The ID of the model to update.data: JSONObject!: The updated data for the model.
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.
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 tohttps://www.builder.ioand should not be changed unless required by the identity provider.
Represents the settings for an OIDC authentication provider, including display name, client ID, and issuer URL.
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).
Represents the claims for generating an embed token, including the space ID and domain.
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.
Represents a query for retrieving content with fields for pagination, filtering, targeting, options, and sorting.
limit: Float: The maximum number of results to return. For example,limit: 10, offset: 10retrieves 10 results starting from the 11th result.offset: Float: The number of results to skip before returning the results. For example,limit: 10, offset: 10retrieves 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 theidis "abc123" and thecustomNumberFieldis less than 100.target: JSONObject: An object representing targeting information. For example,target: { urlPath: "/foobar", device: "mobile" }retrieves content targeted to the URL path/foobaron 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 thecreatedDatefield in descending order.
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: RepresentsNULLvalues.
