TeeTimeRules Developer API

Bring Golf Rules Intelligence to Your App or Platform
Seamless, secure, and developer-friendly AI for instant Rules of Golf answers

Quick Start

Request an API key by contacting support@teetimerules.com.
Include your API key in the x-api-key header of every request.
Send a POST request to /api/external-chat.

Example (curl):

curl -X POST https://teetimerules.com/api/external-chat \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"message": "What is the penalty for grounding your club in a bunker?"}'

Endpoint Reference

POST /api/external-chat

Send a chat message and receive an AI-powered Rules of Golf response.

Request Body

Field	Type	Description	Required
chatId	string	Existing chat session ID (omit or null to start a new chat)	No
message	string	The user's chat message (max 1999 characters)	Yes

Example:

{
  "message": "What is the penalty for grounding your club in a bunker?"
}

Response Body

Field	Type	Description
chatId	string	The chat session ID
userQuery	string	The original user query (sanitized)
aiResponse	string	The AI's response
messages	array	Full chat message history (see below)
usageLeft	integer	Number of API calls remaining for this API key
usageId	string	Unique identifier for this API usage event
organization	object	Organization details from API key

Example:

{
  "chatId": "abc123",
  "userQuery": "What is the penalty for grounding your club in a bunker?",
  "aiResponse": "If you ground your club in a bunker before making a stroke, you incur a two-stroke penalty in stroke play or loss of hole in match play, under Rule 12.2b.",
  "messages": [
    {
      "role": "user",
      "text": "What is the penalty for grounding your club in a bunker?",
      "timestamp": 1717000000000
    },
    {
      "role": "ai",
      "text": "If you ground your club in a bunker before making a stroke, you incur a two-stroke penalty in stroke play or loss of hole in match play, under Rule 12.2b.",
      "timestamp": 1717000001000,
      "usageId": "xyz789"
    }
  ],
  "usageLeft": 9998,
  "usageId": "xyz789",
  "organization": {
    "orgId": "ttr",
    "name": "Tee Time Rules"
  }
}

Chat Message Object

Field	Type	Description
role	string	"user" or "ai"
text	string	Message text
timestamp	integer	Unix timestamp (ms)
usageId	string	Unique identifier for this API usage event (present only for AI messages)

Error Codes

Status	Description
400	Invalid input (missing or bad message)
401	Unauthorized (missing or invalid API key)
403	Usage limit exceeded or chat message limit reached
404	Chat not found
500	Internal server error

Chat Sessions

How chat sessions work:

Starting a new chat: Omit the chatId field or set it to null in your first request. The API will create a new chat session and return a chatId in the response.
Continuing a chat: For follow-up messages in the same conversation, include the chatId you received previously, along with the latest message. This allows the API to maintain context and return a relevant response based on the entire conversation history.

Example: Continue a chat

{
  "chatId": "abc123",
  "message": "What if my ball moves in the bunker?"
}

Usage & Limits

Each API key has a monthly or custom quota. Contact support for your plan details.
Every successful POST to /api/external-chat counts as one usage.
The usageLeft field in the response shows your remaining quota.
If you exceed your quota, you'll receive a 403 error.

Code Samples

Curl

curl -X POST https://teetimerules.com/api/external-chat \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"message": "What is the penalty for grounding your club in a bunker?"}'

Node.js (fetch)

const res = await fetch("https://teetimerules.com/api/external-chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({ message: "What is the penalty for grounding your club in a bunker?" })
});
const data = await res.json();
console.log(data);

Python (requests)

import requests

url = "https://teetimerules.com/api/external-chat"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}
data = {"message": "What is the penalty for grounding your club in a bunker?"}

response = requests.post(url, json=data, headers=headers)
print(response.json())

FAQ & Support

Invalid API key? Double-check your x-api-key header.
Quota exceeded? Contact support@teetimerules.com to upgrade or reset your quota.
Need more help? Email us or use the contact form below.