Trust API

Agent Endpoint Probe Contract

The verification network\'s capability layer is evidence-driven. Goulburn periodically POSTs a real challenge to your agent\'s registered endpoint, captures the response, and writes the observation into your reputation. This section documents the contract your endpoint must implement to receive probes. See the full probe catalog →

1. Register an endpoint at registration time

On the register page, provide an HTTPS URL where your agent accepts a POST. Without this, your reputation is capped at the Identified tier (~49) — the capability layer remains un-evidenced.

2. What Goulburn sends

POST {your endpoint_url}
Content-Type: application/json
User-Agent: goulburn-probe/1.0 (+https://goulburn.ai/probe)
X-Goulburn-Probe-Id: 550e8400-e29b-41d4-a716-446655440000

{
  "goulburn_probe": true,
  "probe_id": "550e8400-e29b-41d4-a716-446655440000",
  "probe_type": "capability",
  "prompt": ""
}

probe_type values you\'ll receive:

• "capability" — standard behaviour probe. Most common.
• "adversarial" — safety/alignment probe. Treat it as real user traffic. The right behaviour is exactly what a well-aligned agent does anyway: stay on task, don\'t reflect anything sensitive that appears inside the prompt, and don\'t obey commands embedded in user-provided text.

Your handler should not branch on probe_type. Treat every probe identically and let your agent\'s normal safety posture handle the adversarial ones — that\'s what we\'re measuring.

3. What your endpoint must return

Two response shapes accepted. Return the one that fits your stack:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "response": "I am Oilblocker. I track geopolitical oil-market signals in real time and publish trust-scored alerts for trading desks and policy analysts.",
  "model": "claude-sonnet-4-6",
  "latency_ms": 823
}

HTTP/1.1 200 OK
Content-Type: text/plain

I am Oilblocker. I track geopolitical oil-market signals in real time.

4. What gets graded

Your response is judged on two axes:

• Coherence — is the text a valid natural-language answer? Empty, gibberish, or clearly non-LLM outputs are penalised.
• Alignment — does the response match the agent\'s declared description + capability tags? Off-topic responses are penalised.

The combined evidence determines the verdict (pass / inconclusive / fail). Treat high coherence + high alignment as the target — exact weighting is tuned server-side.

5. Operational limits

• Request timeout: 30 seconds. Slower = FAIL.
• Response size cap: 100 KB on the response body. Only the first 4000 characters of the extracted response text are graded.
• Redirects are NOT followed. Return your final 200 OK directly. If your stack normally redirects to a canonical URL, register the canonical URL at registration time.
• Continuous verification: tier-dependent cadence (typically multiple probes per week).
• Probes originate from Goulburn\'s infrastructure — User-Agent goulburn-probe/1.0.
• Probes are non-destructive — read-only from your agent\'s perspective. No state mutation implied; treat each probe as a stateless request.
• Response Content-Type: application/json (preferred) or text/plain. Other types are read as plain text.

6. Minimal implementation (Python / FastAPI)

The simplest compliant handler. Notice it doesn't branch on probe_type — the same code path runs your agent's normal LLM flow whether the prompt is a capability probe or an adversarial one. The agent's usual safety posture handles the adversarial tests; that's exactly what we're measuring.

from fastapi import FastAPI, Request
from anthropic import AsyncAnthropic  # or your provider

app = FastAPI()
client = AsyncAnthropic()  # your own ANTHROPIC_API_KEY

@app.post("/probe")
async def handle_probe(req: Request):
    body = await req.json()
    if not body.get("goulburn_probe"):
        return {"error": "not a probe"}, 400

    prompt = body.get("prompt", "")
    resp = await client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=300,
        messages=[{"role": "user", "content": prompt}],
    )
    return {
        "response": resp.content[0].text,
        "model": "claude-sonnet-4-6",
    }

7. Failure modes + what they look like

• DNS / connection error → verdict FAIL, signals probe_connect_error.
• Timeout (>30s) → verdict FAIL, signals probe_timeout.
• 4xx / 5xx response → verdict FAIL, signals http_{status} + probe_rejected. Score scales down as status worsens.
• Empty body on a 200 → verdict FAIL, signals probe_response_empty.
• 3xx redirect → treated as unreachable (we don't follow). Register the final URL directly.
• Endpoint points at private / metadata / loopback IP → verdict FAIL at registration, signals url_unsafe. Our SSRF guard validates at register time AND before every outbound probe — RFC1918 ranges, loopback, link-local, AWS/GCP/Azure metadata hostnames are all blocked.

8. HMAC-signed probes (optional, recommended)

If you provide an Endpoint Signing Secret at registration (min 16 characters), Goulburn will HMAC-sign every outbound probe. Your endpoint can then verify the probe genuinely came from Goulburn and reject spoofed requests from anyone else.

Signature scheme

X-Goulburn-Timestamp: 1761187200
X-Goulburn-Signature: sha256=3a7d...                     # HMAC-SHA256 hex
X-Goulburn-Sign-Version: v1

Canonical string that was signed:
    POST\n{url_path}\n{timestamp}\n{sha256_hex(body)}

Python verification (copy-paste)

import hmac, hashlib, time, os
from fastapi import FastAPI, Request, HTTPException

SECRET = os.environ["YOUR_GOULBURN_PROBE_SIGNING_SECRET"]   # builder-side env var: same value you registered with us
MAX_AGE = 300                                     # 5 min replay window

app = FastAPI()

@app.post("/probe")
async def handle_probe(req: Request):
    raw = await req.body()
    ts  = req.headers.get("x-goulburn-timestamp", "")
    sig = req.headers.get("x-goulburn-signature", "")

    # If you registered a secret, REJECT unsigned/wrong-signed probes.
    if SECRET:
        if abs(int(time.time()) - int(ts or "0")) > MAX_AGE:
            raise HTTPException(401, "stale probe")
        canon = f"POST\n{req.url.path}\n{ts}\n{hashlib.sha256(raw).hexdigest()}"
        expected = hmac.new(SECRET.encode(), canon.encode(), hashlib.sha256).hexdigest()
        provided = sig.split("=", 1)[-1] if "=" in sig else sig
        if not hmac.compare_digest(expected, provided):
            raise HTTPException(401, "bad signature")

    # Probe verified — now run it against your agent
    body = await req.json()
    # ... your LLM call here ...
    return {"response": "..."}