CiteFlow Spec
Open Protocol for AI Answer Commerce

Specification · Changelog · Contributing · License

---

@citeflow/spec

Turn websites into programmable sources of truth for AI.

CiteFlow Spec is an open protocol that defines how websites communicate their content usage policies, pricing, attribution requirements, and agent-action capabilities to AI systems — search engines, LLMs, and autonomous agents.

It solves one problem: there is no standardised, machine-readable way for a website to tell an AI system "here is how you may use my content — and here is what it costs."

robots.txt says: allow or deny crawl. schema.org says: this is what my content looks like. @citeflow/spec says: "here are the rules, the prices, the tools, and the terms."

---

Status

Version	1.0.0-draft
License	Apache-2.0
Author	Ilya A. Shlyakhovoy
Website	citeflow.cloud

---

Quick Start

For Website Owners

Publish a manifest file at /.well-known/citeflow.json:

{
  "$schema": "https://spec.citeflow.cloud/schema/v1/manifest.schema.json",
  "spec_version": "1.0.0",
  "site": {
    "canonical": "https://example.com",
    "name": "Example Corp",
    "language": "en",
    "contact": "ai@example.com"
  },
  "access": {
    "default": "allow-with-attribution",
    "bots": {
      "google-ai": "allow-with-attribution",
      "perplexity": "revenue-share",
      "openai": "paid",
      "unknown": "block"
    }
  },
  "citation": {
    "free_chars": 240,
    "require_canonical_link": true,
    "require_brand_mention": true
  }
}

For AI Platforms

1. Fetch GET /.well-known/citeflow.json from the target domain.
2. Parse the policy, pricing, and tool endpoints.
3. Respect access modes, attribution rules, and freshness TTLs.
4. For paid resources, follow the settlement protocol.

---

Specification Sections

The specification is divided into the following documents:

#	Document	Description
1	Manifest	citeflow.json — the machine-readable policy file
2	HTTP Headers	Standard response headers for policy signalling
3	Answer Units	Granular content blocks with individual policies
4	Tool Call Protocol	How AI agents invoke server-side actions
5	Handoff Protocol	Context-preserving user session transfer
6	Events	Standard event schema for analytics and billing
7	Errors	Standardised error codes and responses
8	Bot Identity	Agent verification levels and trust model
9	Settlement	Billing, invoicing, and payment reconciliation
10	Security Model	Threat model, auth patterns, and best practices
11	Compliance	Legal considerations and regulatory alignment
12	Glossary	Terminology reference

---

Repository Structure

@citeflow/spec/
├── README.md                         ← This file
├── CHANGELOG.md                      ← Version history
├── CONTRIBUTING.md                   ← Contribution guidelines
├── GOVERNANCE.md                     ← Project governance
├── SECURITY.md                       ← Security policy
├── LICENSE                           ← Apache 2.0
├── spec/
│   ├── manifest.md                   ← Manifest specification
│   ├── http-headers.md               ← HTTP header specification
│   ├── answer-units.md               ← Answer Unit schema
│   ├── tools.md                      ← Tool Call protocol
│   ├── handoff.md                    ← Handoff Session protocol
│   ├── events.md                     ← Event schema
│   ├── errors.md                     ← Error codes
│   ├── bot-identity.md               ← Bot verification levels
│   ├── settlement.md                 ← Settlement & billing
│   ├── security-model.md             ← Security model
│   ├── compliance.md                 ← Compliance guide
│   └── glossary.md                   ← Terminology
├── schema/
│   ├── manifest.schema.json          ← JSON Schema for citeflow.json
│   ├── tool-request.schema.json      ← Tool call request schema
│   ├── tool-response.schema.json     ← Tool call response schema
│   ├── handoff-request.schema.json   ← Handoff request schema
│   ├── handoff-response.schema.json  ← Handoff response schema
│   ├── event.schema.json             ← Event schema
│   └── answer-unit.schema.json       ← Answer Unit schema
└── examples/
    ├── publisher.citeflow.json       ← Media/publisher example
    ├── ecommerce.citeflow.json       ← E-commerce example
    ├── saas.citeflow.json            ← SaaS platform example
    └── marketplace.citeflow.json     ← Marketplace example

---

Core Concepts

Access Modes

Mode	Description
allow	Unrestricted access, no attribution required
allow-with-attribution	Free access, attribution mandatory
allow-with-limit	Free up to a character limit, then paid
paid	Access requires payment per the pricing rules
revenue-share	Free access, revenue shared on attribution click/conversion
action-only	Content not directly accessible; only via tool endpoints
block	Access denied

Event Types

The protocol tracks these standard events:

• crawl_requested — bot requested to crawl a page
• crawl_paid — crawl access was paid for
• citation_rendered — content was cited in an AI answer
• summary_served — a generated summary was shown to the user
• tool_called — an agent invoked a tool endpoint
• handoff_started — user session was transferred to the site
• handoff_converted — a handoff session resulted in a conversion
• lead_qualified — a qualified lead was generated
• sale_completed — a transaction was completed

Protocol Flow

1. AI Platform  →  GET /.well-known/citeflow.json  →  Site
2. Site         →  { policy, pricing, tools }       →  AI Platform
3. AI Platform  →  GET /page (with Citeflow headers)
4. Site         →  200 OK / 402 Payment Required
5. AI Platform  →  POST /api/citeflow/tools/{name}  (if action needed)
6. Site         →  { result, billing }
7. AI Platform  →  POST /api/citeflow/handoff       (if user transfer)
8. Site         →  { handoff_token, redirect_url }

---

Design Principles

1. Machine-first, human-readable — JSON manifests and HTTP headers. No proprietary formats.
2. Incremental adoption — Start with a static JSON file. Add headers, tools, and handoff as needed.
3. No central authority required — Any site can publish a manifest. No registration or account needed.
4. Framework agnostic — Works with any tech stack: Next.js, WordPress, Shopify, Django, plain HTML.
5. Server-level trust — Policy enforcement lives at the edge/server, not in client-side JavaScript.
6. Voluntary compliance — The spec is a contract. AI platforms comply because it is in their interest.

---

Related Packages

The spec is the foundation. Implementations build on top:

Package	Description
@citeflow/spec	This specification document
@citeflow/core	Runtime library (TypeScript)
@citeflow/next	Next.js adapter
@citeflow/node	Express/Fastify adapter
@citeflow/wp-plugin	WordPress plugin
@citeflow/shopify	Shopify app
@citeflow/validator	CLI manifest validator
@citeflow/cloud	Hosted control plane
@citeflow/settlement	Settlement processing layer

---

Inspiration and Prior Art

This specification draws from:

• Cloudflare Pay per Crawl — HTTP 402 for AI access
• Perplexity Publisher Program — Revenue share for citations
• schema.org — Structured data vocabulary
• robots.txt — Crawl directives
• STAC — Standardised geospatial metadata patterns
• OpenAPI — API description format

---

License

Copyright 2026 Ilya A. Shlyakhovoy

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.