Core GraphQL API

What is the Core GraphQL API?Copy Anchor Link

The Core API is what the StoreOS console runs on. Use it to build your own admin tools, sync products from another system, or automate store operations. Shoppers never call it. Storefronts use the Storefront GraphQL API instead.

POST https://api.storeos.dev/core/graphql

The schema loads in the playground without a key. Running a query needs the headers below.

HeadersCopy Anchor Link

The key tells the gateway which store you are acting on, so you don't send x-tenant yourself. Create the key under Organization settings → API keys (guide).

Sign in, then call an operationCopy Anchor Link

Staff tokens come from the public identity__login mutation:

mutation {
  identity__login(input: { email: "owner@example.com", password: "…" }) {
    accessToken
  }
}

Send the returned token as Authorization: Bearer <accessToken>. Then list products:

query {
  inventory__products(where: { page: 1, limit: 10 }) {
    nodes {
      _id
      title
      price
      status
    }
    meta {
      totalCount
      hasNextPage
    }
  }
}

curl https://api.storeos.dev/core/graphql \
  -H "x-storeos-key: sos_live_YOUR_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ inventory__products(where: {page: 1, limit: 10}) { nodes { _id title } } }"}'

PermissionsCopy Anchor Link

A valid token isn't enough on its own. Each operation checks the signed-in user's role, for example inventory__Product → read. The reference lists the permission every operation needs. A missing permission returns a GraphQL error, and the user's role is managed in the console under Organization settings → Roles.

NamingCopy Anchor Link

Operations are named {domain}__{operation}, such as inventory__createProduct or sale__invoices. A few older ones have no prefix, such as createCoupon.

ReferenceCopy Anchor Link

Every query, mutation and type has its own page, generated from the live schema. Find them in the sidebar under Reference.

• Operation pages show the arguments, the return type, an example request and response, and the role permission the operation needs.
• Each one has a Try in Playground button that sends real requests to the gateway. Paste your key and token into its header rows first.
• Types link to each other, so you can follow ProductsWithPagination down to Product and its fields.

Start with inventory__products or the Product type.