BaseHub Logo

BaseHub Logo

Query API

BaseHub distributes content via a GraphQL API. Anything that can query GraphQL will work to query our API. We serve all GraphQL requests through a single endpoint:

https://api.basehub.com/graphql

To query data from your repository, you’ll need to send an Authorization header with Bearer <read-token> as its value. Here are some examples

You can also authenticate in other ways:

  • Via an x-basehub-token header with the token directly (no “Bearer” scheme)

  • Via a token query parameter, also with the token directly (not recommended)

By default, the GraphQL API will respond with the default Branch’s head Commit data. In simpler terms, it’ll respond with the data from your latest Commit.

There are ways to get working/draft (non-committed) content, and also getting data from a specific Commit from time ago. Let’s explore how.

Getting Working/Draft Content

You have two ways of getting Working/Draft content:

  1. By passing a x-basehub-draft header with “true“ as its value

  2. By passing a draft query parameter with “true“ as its value

You will notice that the API will respond much slower than normal. This is because we don’t cache Draft API requests.

Getting Data from a Specific Commit

You have two ways of getting content from a specific commit:

  1. By passing a x-basehub-ref header with the Commit ID as its value

  2. By passing a ref query parameter with the Commit ID as its value

You can get a Commit ID via the Commits Tab (in the Repo Dashboard, in the middle of the header).

API Design

Our API Design is intentionally simple. As you start exploring the GraphQL schema, you’ll notice that it’s closely related to how your sidebar looks like. For the following Tree structure:

- Document Block: Blog
  - Text Block: Hero Title
  - Collection Block: Blog Posts
    - Rich Text Block: Content
    - Image Block: Cover Image
    - Date Block: Publish Date
    - Reference Block: Author

the API will generate a schema like the following (represented in TypeScript :

Explorer/GraphiQL

You’ll be able to explore your GraphQL API in the Explore Panel, available in this route:

https://basehub.com/<team>/<repo>/connect/explore