Skip to main content

Customer API Endpoint

The Customer API is available at a dedicated endpoint for customer operations.

Endpoint​

https://handbooks.io/api/graphql-public

Making Requests​

All requests to the Customer API should be:

  • Method: POST
  • Content-Type: application/json
  • Authorization: Bearer <your_jwt_token>
  • Body: JSON object with query/mutation

Basic Request Structure​

{
  "query": "query { health { status } }",
  "variables": {}
}

Example with Variables​

{
  "query": "query GetHandbook($handbookId: String!) { getHandbook(handbookId: $handbookId) { handbookId createdAt } }",
  "variables": {
    "handbookId": "handbook_123"
  }
}

Using cURL​

curl -X POST https://handbooks.io/api/graphql-public \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_bearer_token_here" \
  -d '{
    "query": "query { health { status timestamp } }"
  }'

Using JavaScript/TypeScript​

const response = await fetch('https://handbooks.io/api/graphql-public', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_bearer_token_here',
  },
  body: JSON.stringify({
    query: `
      query {
        health {
          status
          timestamp
        }
      }
    `,
  }),
});

const data = await response.json();

Using GraphQL Clients​

Apollo Client​

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://handbooks.io/api/graphql-public',
  headers: {
    'Authorization': 'Bearer your_bearer_token_here',
  },
  cache: new InMemoryCache(),
});

const { data } = await client.query({
  query: gql`
    query {
      health {
        status
        timestamp
      }
    }
  `,
});

GraphQL Request​

import { request, gql } from 'graphql-request';

const endpoint = 'https://handbooks.io/api/graphql-public';

const query = gql`
  query {
    health {
      status
      timestamp
    }
  }
`;

const data = await request(endpoint, query, {}, {
  'Authorization': 'Bearer your_bearer_token_here',
});

Response Format​

All responses follow the GraphQL specification:

Success Response​

{
  "data": {
    "health": {
      "status": "ok",
      "timestamp": "2025-01-15T10:30:00Z"
    }
  }
}

Error Response​

{
  "errors": [
    {
      "message": "Invalid token",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ],
  "data": null
}

Rate Limiting​

Currently, there are no strict rate limits, but we recommend:

  • Batching requests when possible
  • Implementing retry logic with exponential backoff
  • Caching responses when appropriate

For high-volume usage, please contact [email protected] to discuss rate limits and best practices.