The GraphQL API


When you define a schema, TinaCMS will generate a GraphQL API which treats your local filesystem as a database. You can serve this schema locally via the CLI or you can consume it from Tina Cloud.

Note: The following schema is used in all examples

// .tina/schema.ts
import { defineSchema } from '@tinacms/cli'

export default defineSchema({
  collections: [
    {
      label: 'Blog Posts',
      name: 'post',
      path: 'content/posts',
      format: 'json',
      fields: [
        {
          type: 'string',
          label: 'Title',
          name: 'title',
        },
        {
          type: 'string',
          label: 'Category',
          name: 'category',
        },
        {
          type: 'reference',
          label: 'Author',
          name: 'author',
          collections: ['author'],
        },
      ],
    },
    {
      label: 'Authors',
      name: 'author',
      format: 'json',
      path: 'content/authors',
      fields: [
        {
          type: 'string',
          label: 'Name',
          name: 'name',
        },
        {
          type: 'string',
          label: 'Avatar',
          name: 'avatar',
        },
      ],
    },
  ],
})

Schema-specific Queries

The GraphQL API will generate queries which are specific to the schema you define. For a given collection, it's name will be used to generate get{name}Document and get{name}List queries, and the update{name}Document mutation. You'll also notice the resulting type is based on the collection name. Given the schema above, you'll find the following queries and mutations:

get{name}Document

Get a single document, providing it's relativePath as the argument. relativePath is the portion of the path relative to the collection's path. So in this example, the post collection has a path of content/posts. And your document can be found at content/posts/voteForPedro.md, so relativePath: "voteForPedro.md". If your item was at content/posts/nested-folder/voteForPedro.md you'd specify: relativePath: "nested-folder/voteForPedro.md".

getPostDocument

getAuthorDocument

get{name}List

List queries offer limited functionality for now.

  • Because of the nature of list items, we don't currently auto-generate Tina forms for these queries.
  • Depending on how many items you may have in your collection, the query could be quite slow. We'll be working on a more robust data layer to improve this experience in the near future.

General queries

getDocument

getCollections

getCollection

Schema-specific Mutations

Note: Update mutations will overwrite all fields. Omitting a field will result in it being nullified.

update{name}Document

updatePostDocument

updateAuthorDocument

General Mutations

addPendingDocument

Note: addPendingDocument does not currently support fields of any kind, just creating the record.

updateDocument