> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heychocolate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Hey Chocolate GraphQL API.

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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```graphql theme={null}
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:

```graphql theme={null}
query {
  __schema {
    types {
      name
      description
    }
  }
}
```

## Schema overview

<CardGroup cols={2}>
  <Card title="Queries" icon="magnifying-glass">
    Read data: products, customers, orders, supply chains, search, and DPPs.
  </Card>

  <Card title="Mutations" icon="pen">
    Write data and trigger actions: calculations, scenarios, orders, and asset generation.
  </Card>

  <Card title="Types" icon="database">
    Core data types: Customer, Product, Order, SupplyChain, Transaction, ShoppingCart, DPP.
  </Card>

  <Card title="Enums" icon="list">
    Sector tags, transport methods, energy sources, lifecycle phases, and more.
  </Card>
</CardGroup>