Register Now: Use Visual Dev + AI to Ship 10x Faster on July 24

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Contact Sales
Platform
Developers
Contact Sales

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

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 to https://www.builder.io and 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: 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.

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?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy

Product

Visual Copilot

Visual Headless CMS

Integrations

What's New

Open Source

Builder

Builder

Mitosis

Mitosis

Qwik

Qwik

Partytown

Partytown

Popular Guides

From Design to Code Ebook

SaaS Marketing Site Ebook

Composable Commerce Ebook

Headless CMS Guide

Headless Commerce Guide

Design to Code

Resources

Blog

Knowledge Base

Community Forum

Partners

Performance Insights

Templates

Success Stories

Showcase

Resource Center

Frameworks

React

React

Next

Next.js

Qwik

Qwik

Gatsby

Gatsby

Angular

Angular

Vue

Vue

Svelte

Svelte

Remix logo

Remix

Nuxt

Nuxt

Hydrogen

Hydrogen

Builder.io logo

Visually build and optimize digital experiences on any tech stack. No coding required, and developer approved.

Get StartedLog In
© 2024 Builder.io, Inc.

Security

Privacy Policy

SaaS Terms

Security & Compliance

Cookie Preferences