API Reference - Hey Chocolate

The Hey Chocolate API is a GraphQL API that provides a single endpoint for all operations. GraphQL allows you to request exactly the data you need and combine multiple resources in a single request.

Endpoint

POST https://api.heychocolate.com/graphql

Sandbox environment:

POST https://sandbox.heychocolate.com/graphql

Making requests

All requests are POST requests with a JSON body containing the GraphQL query:

curl -X POST https://api.heychocolate.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_key_here" \
  -d '{
    "query": "query { products(first: 10) { edges { node { id name } } } }",
    "variables": {}
  }'

Request format

Field	Type	Required	Description
`query`	String	Yes	The GraphQL query or mutation
`variables`	Object	No	Variables referenced in the query
`operationName`	String	No	Name of the operation (when sending multiple)

Response format

Every response follows the standard GraphQL response format:

{
  "data": { ... },
  "errors": [ ... ],
  "extensions": {
    "requestId": "req_abc123",
    "cost": 12,
    "rateLimit": {
      "remaining": 588,
      "resetAt": "2025-09-01T12:01:00Z"
    }
  }
}

Pagination

The API uses cursor-based pagination following the Relay Connection specification:

query {
  products(first: 20, after: "cursor_abc") {
    edges {
      node { id name }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Introspection

The GraphQL schema is fully introspectable. Use your favorite GraphQL client (GraphiQL, Apollo Studio, Insomnia) to explore the schema:

query {
  __schema {
    types {
      name
      description
    }
  }
}

Schema overview

Queries

Read data: products, customers, orders, supply chains, search, and DPPs.

Mutations

Write data and trigger actions: calculations, scenarios, orders, and asset generation.

Types

Core data types: Customer, Product, Order, SupplyChain, Transaction, ShoppingCart, DPP.

Enums

Sector tags, transport methods, energy sources, lifecycle phases, and more.

​Endpoint

​Making requests

​Request format

​Response format

​Pagination

​Introspection

​Schema overview