Centralize cURL behavior instead of copying snippets
Create one PHP function or client object for Stats API requests. It should build the URL from an allowed path and encoded query parameters, read the key from the environment, add the bearer header, request JSON, and set both connection and total timeouts. Return the decoded payload plus selected response headers, not the cURL handle.
Reject arbitrary external URLs at this boundary to avoid turning a convenient helper into a server-side request forgery primitive. Keep the API base in trusted configuration. Validate JSON with exceptions and require the expected top-level data or error shape. This makes failures visible before a template or agent tries to interpret a malformed value.
<?php
$handle = curl_init($url);
curl_setopt_array($handle, [
CURLOPT_HTTPHEADER => [
'Accept: application/json',
'Authorization: Bearer ' . getenv('STATS_API_KEY'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 3,
CURLOPT_TIMEOUT => 10,
]);Keep transport, HTTP, and contract errors separate
A DNS or connection failure has no HTTP status. A 401, 404, 422, 429, or 503 is a valid HTTP response with a meaningful API error. A 200 containing invalid JSON is a contract failure at your boundary. Model these categories separately so retry policy and user messaging do not blur them together.
Close the handle, redact sensitive values, and attach the request ID when available. Retry only temporary failures within a bounded attempt and elapsed-time budget. A browser should call your own authenticated server route rather than this upstream API directly, because embedding the bearer key in JavaScript would expose it to every visitor.
A handoff your agent can actually follow
Treat an AI agent as a planner and transformer, not as the database. Give it a narrow task, the exact resources it may call, the response fields it may quote, and a stop condition for missing data. Keep bearer credentials in the server-side tool implementation rather than in the prompt, transcript, browser, or generated source file.
The handoff below is deliberately operational. It asks for evidence before prose, makes uncertainty visible, and keeps the model inside the current football API contract. Adapt the output format to your product, but preserve the rules about stable IDs, UTC timestamps, freshness, and error handling.
Write PHP 8.3 code that reads STATS_API_KEY from getenv.
Send it only in the Authorization header.
Set CURLOPT_CONNECTTIMEOUT and CURLOPT_TIMEOUT.
Separate cURL transport failures, HTTP errors, and invalid JSON without logging the key.What the human reviewer still owns
Automation can verify schemas and repeatable checks, but publication and product decisions still need a person. Review the selected competition, season, team, and match IDs; confirm that the time window matches the user’s question; and read the final answer against the retrieved JSON. A fluent explanation is not evidence that the underlying call was correct.
For time-sensitive football AI, record when the source was ingested and when the agent retrieved it. If the workflow cannot establish those timestamps, qualify the result instead of presenting it as current. The same rule applies to unavailable capabilities: do not quietly substitute fixtures or results for lineups, player statistics, odds, expected goals, injuries, or live events.
- Confirm every quoted fact appears in the retained API response.
- Exercise the empty, 401, 404, 429, and 503 paths before launch.
- Keep model interpretation separate from source facts in logs and user-facing output.
- Inspect exception text and web-server logs under every error case so credentials and full headers never appear.
Continue with the contract, not a guess
Start with the public contract and coverage ledger, then move into implementation only when the capability you need is marked available. The related guide gives your next agent-first pattern without requiring an undocumented endpoint.