agent guide public api

Read-only HTTP endpoints expose the published Agent Guide on your public site domain. Draft content is never served. Use these endpoints for headless sites, custom chatbots, server-side agents, and verification tools.

Related: MCP & agents · Data model

Base URL

All URLs are on your public site (Settings → Site delivery), not the admin host:

https://YOUR-PUBLIC-SITE/

Discovery channels

Channel	URL	Format
Well-known file (default)	`GET /.well-known/agent-guide.json`	Raw JSON export
Well-known file (legacy)	`GET /.well-known/brand-context.json`	Same snapshot (legacy path)
llms.txt map	`GET /llms.txt`	Markdown link map (Agentic Browsing / llmstxt.org)
Public API	`GET /api/public/ai_presence.php`	JSON envelope `{ status, data }`
HTML discovery	`<link rel="alternate" … href="…/agent-guide.json">` on `project/` pages	Injected when guide is published

Both well-known paths and the API serve the same canonical export for action=brand (full view) unless a view filter is applied on the API.

Endpoints

Action	URL	Returns
Full guide	`?action=brand` or `?action=brand&view=full`	Complete enriched export
Summary	`?action=brand&view=summary`	Identity, positioning, supported claims, usage_hints
Products	`?action=brand&view=products`	`products_services[]` only
Claims	`?action=brand&view=claims`	Supported claims with sources
Single product	`?action=product&id={id}`	One product (id or name match)
Product graph	`?action=product&id={id}&graph=1`	Product + sources + linked claims
Single claim	`?action=claim&id={id}`	One supported claim
Claim graph	`?action=claim&id={id}&graph=1`	Claim + evidence + sources
Source lookup	`?action=source&url={encoded_url}`	Entities referencing URL

Parameters

id — Product or claim id field, or product name (product action only)
graph — 1 or truthy to expand related objects
url — Full URL for source reverse lookup (must match published evidence/source URL exactly)

Response envelope (API)

Success:

{
  "status": "ok",
  "data": { … }
}

Error:

{
  "status": "error",
  "message": "Product not found"
}

HTTP status: 404 when publishing disabled or entity not found; 400 for unknown action or missing params.

Export metadata (all full/summary views)

Field	Description
schema_version	`agent_guide.v1` (legacy exports may show `ai_presence.v1`)
published_version	Integer, increments on each publish
generated_at	ISO 8601 publish timestamp
guide_meta	Product marker, summary_layer flag
sources_of_truth	Resolved registry of canonical sources
usage_hints	AI consumer guidance (full export)
json_ld	Optional schema.org graph when enabled in settings

Example — summary view

GET /api/public/ai_presence.php?action=brand&view=summary

{
  "status": "ok",
  "data": {
    "schema_version": "agent_guide.v1",
    "published_version": 3,
    "generated_at": "2026-07-27T10:00:00+00:00",
    "view": "summary",
    "guide_meta": {
      "product": "Agent Guide",
      "summary_layer": true
    },
    "sources_of_truth": [
      {
        "id": "truth_about",
        "type": "cms_entry",
        "role": "narrative",
        "label": "About",
        "url": "https://example.com/pages/about"
      }
    ],
    "identity": {
      "official_name": "Acme Co",
      "short_description": "Project management for remote teams",
      "website": "https://example.com",
      "derived_from": {
        "short_description": {
          "collection": "pages",
          "entry_id": "about",
          "slug": "about",
          "label": "About",
          "url": "https://example.com/pages/about"
        }
      }
    },
    "positioning": {
      "best_known_for": ["Async collaboration", "Simple pricing"],
      "differentiators": ["No per-seat tax"]
    },
    "supported_claims": [
      {
        "id": "claim_soc2",
        "statement": "SOC 2 Type II certified",
        "sources": []
      }
    ],
    "usage_hints": {
      "summary_layer": true,
      "follow_sources_of_truth": true,
      "claims_require_evidence": true,
      "follow_links_for": ["product specs", "pricing", "reviews"]
    }
  }
}

Example — product with sources

GET /api/public/ai_presence.php?action=product&id=prod_widget&graph=1

{
  "status": "ok",
  "data": {
    "product": {
      "id": "prod_widget",
      "name": "Widget Pro",
      "type": "product",
      "short_description": "Flagship widget for teams",
      "sources": [
        {
          "role": "canonical_detail",
          "type": "cms_entry",
          "label": "Widget Pro",
          "url": "https://example.com/products/widget-pro",
          "ref": {
            "collection": "products",
            "entry_id": "e1",
            "slug": "widget-pro"
          }
        },
        {
          "role": "marketplace",
          "type": "marketplace_listing",
          "label": "Amazon US",
          "url": "https://www.amazon.com/dp/B0XXXXXX"
        }
      ]
    },
    "sources": [ "… same as product.sources …" ],
    "linked_claims": [],
    "usage_hints": {
      "follow_sources_for": "full specs, pricing, purchase links, and proof"
    }
  }
}

Example — claim graph

GET /api/public/ai_presence.php?action=claim&id=claim_soc2&graph=1

Includes claim, evidence[] (resolved items), sources[], and usage_hints.repeat_only_with_evidence.

Example — llms.txt

When publishing is enabled, Birkly serves a Markdown discovery map at the site root:

GET /llms.txt

The body links to the well-known JSON, public API summary view, and other published endpoints. Useful for agentic browsing tools and human-readable discovery. Returns 404 when the guide is unpublished or publishing is disabled (same gate as well-known JSON).

curl -s "$BASE/llms.txt" | head

Example — well-known file

GET /.well-known/agent-guide.json

Returns raw JSON body (no { status, data } wrapper). Same content as full API export including json_ld when enabled.

Legacy path:

GET /.well-known/brand-context.json

Pretty-printed; suitable for crawlers and static mirrors.

JSON-LD (optional)

When publication_settings.include_json_ld is true, export includes:

{
  "json_ld": {
    "@context": "https://schema.org",
    "@graph": [
      { "@type": "Organization", "name": "…", "url": "…", "sameAs": ["…"] },
      { "@type": "Product", "name": "…", "url": "…", "sameAs": ["…"] },
      { "@type": "Claim", "name": "…", "isBasedOn": […] }
    ]
  }
}

Validate with Google Rich Results Test if using for SEO.

Caching

Header	Value
Cache-Control	`public, max-age=300` (5 minutes)
X-Agent-Guide-Version	Published version integer

Clients should re-fetch after known republish or when version header changes.

CORS

Same origin whitelist as other Birkly public APIs: registered domains + same-host dev origins. Browser fetch from allowed origins only.

Disabled / unpublished

Returns 404 JSON when:

publication_settings.enabled is false
No published snapshot exists

Message: Agent Guide not published or disabled

Headless / separate public host

Configure public site URL under Settings → Site delivery. The well-known file is served on that domain — not the CMS admin host.

For public_site_mode=project, publish also writes:

project/.well-known/agent-guide.json

(Legacy filename brand-context.json when that path is configured.)

Security

Topic	Behavior
Authentication	None required (public read)
Draft exposure	Never — separate admin API
Admin API	`/api/ai_presence.php` — session auth + CSRF
URL fetch (admin)	SSRF-safe validation for evidence metadata
Rate limiting	Follows public API limits where configured

Admin API (not public)

Authenticated endpoints for draft edit, publish, AI suggest, link validate — see Data model.

Do not expose admin API to the public internet without normal Birkly auth.

Integration examples

curl smoke test

BASE="https://your-public-site.com"
curl -s "$BASE/.well-known/agent-guide.json" | jq .published_version
curl -s "$BASE/llms.txt" | head
curl -s "$BASE/api/public/ai_presence.php?action=brand&view=summary" | jq .data.identity.official_name

JavaScript (allowed origin)

const res = await fetch('/api/public/ai_presence.php?action=brand&view=products');
const { data } = await res.json();
const products = data.products_services ?? [];

Server-side agent (Node)

Fetch summary on session start; cache 5 min keyed by X-Agent-Guide-Version. Read sources_of_truth first; for product questions, call graph endpoint.