Documentation

FlyWeb Docs

Everything you need to make your website visible to AI. From zero to FlyWeb-enabled in 5 minutes.

1. What is FlyWeb?

FlyWeb is an open protocol that makes websites machine-readable. Every website publishes a single JSON file at /.well-known/flyweb.json that tells AI agents:

What content you have — posts, products, pages, APIs
Where to find it — structured data endpoints, not HTML
How to query it — standard URL parameters for filtering
How to credit you — enforced attribution at the protocol level

Think of it as SEO for the AI era. Google had robots.txt and sitemap.xml. AI agents need flyweb.json.

The Three Layers:

Discovery — /.well-known/flyweb.json advertises your resources
Structure — Content served as clean JSON/JSONL, not HTML
Query — ?tag=ai&limit=10 for filtering and pagination

2. Quick Start

Option A: Use a framework plugin (recommended)

npm install next-flyweb # Next.js

npm install astro-flyweb # Astro

npm install sveltekit-flyweb # SvelteKit

npm install nuxt-flyweb # Nuxt

npm install express-flyweb # Express/Node.js

Option B: Use the CLI (any website)

$ npx flyweb init > public/.well-known/flyweb.json

Edit the generated file with your entity name, type, and resources. Deploy.

Option C: WordPress

Download the FlyWeb WordPress plugin
Upload to /wp-content/plugins/ and activate
Go to Settings > FlyWeb — configure and save
Your site is now FlyWeb-enabled. Zero code.

Verify it works:

$ npx flyweb check https://yoursite.com

✓ Valid FlyWeb v1.0 config

✓ All checks passed!

3. The Spec

The flyweb.json file must be served at /.well-known/flyweb.json with Content-Type: application/json.

Schema

Field	Type	Required	Description
flyweb	"1.0"	Yes	Protocol version
entity	string	Yes	Site or org name
type	string	Yes	blog, news, ecommerce, docs, api, saas, science, etc.
url	string	No	Canonical site URL
description	string	No	Human-readable description
attribution	object	No	Attribution requirements (see below)
resources	object	Yes	Map of resource name → resource config

Resource Schema

Field	Type	Required	Description
path	string	Yes	URL path starting with /
format	string	Yes	json, jsonl, csv, or xml
fields	string[]	Yes	Available data fields
query	string	No	Query template with {param} placeholders
access	string	No	"free" (default), "paid", or "blocked"
description	string	No	Human-readable description
auth	boolean	No	Whether auth is required

Full specification: SPEC.md on GitHub

4. Attribution

Attribution is enforced at the protocol level. You can set price to zero. You can never set attribution to zero.

attribution object

"attribution": {
  "required": true,            // must credit source
  "format": "Source: {entity} — {url}",  // how to format it
  "license": "CC-BY-4.0",       // content license
  "must_link": true           // must include URL
}

Field	Description
required	Whether attribution is required (default: true)
format	Template string for how AI should format the credit. Use {entity} and {url} placeholders.
license	Content license (CC-BY-4.0, MIT, CC-BY-NC-4.0, etc.)
must_link	Whether AI responses must include a link back to source

5. Access Tiers

Each resource has an access field that controls how AI agents can interact with it:

"free"

Default. AI reads your content for free but must follow attribution rules.

"paid"

AI must pay to access. Payment integration coming soon.

"blocked"

AI agents cannot access this resource. Useful for premium content.

Start with "free". When you're ready to monetize, change one line to "paid". No migration needed.

6. Framework Guides

Next.js

npm install next-flyweb

Create app/.well-known/flyweb.json/route.ts:

import { createHandler } from 'next-flyweb';

export const GET = createHandler({
  flyweb: '1.0',
  entity: 'My Blog',
  type: 'blog',
  attribution: { required: true, license: 'CC-BY-4.0', must_link: true },
  resources: {
    posts: {
      path: '/.flyweb/posts',
      format: 'jsonl',
      fields: ['title', 'author', 'date', 'content'],
      query: '?tag={tag}',
      access: 'free',
    },
  },
});

Then create app/.flyweb/posts/route.ts to serve the actual data:

import { createResourceHandler } from 'next-flyweb';
import { getAllPosts } from '@/lib/posts';

export const GET = createResourceHandler({
  format: 'jsonl',
  source: getAllPosts,
  queryable: ['tag', 'author'],
  maxLimit: 50,
});

SvelteKit

npm install sveltekit-flyweb

Create src/routes/.well-known/flyweb.json/+server.ts:

import { createHandler } from 'sveltekit-flyweb';

export const GET = createHandler({
  flyweb: '1.0',
  entity: 'My App',
  type: 'saas',
  resources: {
    docs: {
      path: '/.flyweb/docs',
      format: 'jsonl',
      fields: ['title', 'slug', 'content'],
    },
  },
});

Astro

npm install astro-flyweb

Add to astro.config.mjs:

import flyweb from 'astro-flyweb';

export default defineConfig({
  integrations: [
    flyweb({
      entity: 'My Docs',
      type: 'docs',
      resources: {
        pages: {
          path: '/.flyweb/pages',
          format: 'jsonl',
          fields: ['title', 'slug', 'content'],
        },
      },
    }),
  ],
});

Generates public/.well-known/flyweb.json automatically during build.

Express / Node.js

npm install express-flyweb

import express from 'express';
import { flyweb, createResourceHandler } from 'express-flyweb';

const app = express();

// Middleware: serves flyweb.json at /.well-known/flyweb.json
app.use(flyweb({
  flyweb: '1.0',
  entity: 'My API',
  type: 'api',
  resources: {
    items: {
      path: '/.flyweb/items',
      format: 'json',
      fields: ['id', 'name', 'description'],
      access: 'free',
    },
  },
}));

// Resource handler with filtering
app.get('/.flyweb/items', createResourceHandler({
  format: 'json',
  source: () => getItems(),
  queryable: ['category'],
}));

Nuxt

npm install nuxt-flyweb

Add to nuxt.config.ts:

import flyweb from 'nuxt-flyweb';

export default defineNuxtConfig({
  modules: [
    [flyweb, {
      entity: 'My Site',
      type: 'blog',
      resources: {
        posts: {
          path: '/.flyweb/posts',
          format: 'jsonl',
          fields: ['title', 'author', 'content'],
        },
      },
    }],
  ],
});

Static Site / Manual

Create public/.well-known/flyweb.json manually or with the CLI:

npx flyweb init > public/.well-known/flyweb.json

Then create your resource endpoint(s) that serve structured JSON/JSONL data at the paths you defined.

7. WordPress

The FlyWeb WordPress plugin auto-generates everything. Zero code required.

Download from GitHub
Upload to /wp-content/plugins/flyweb/
Activate in Plugins menu
Go to Settings > FlyWeb
Configure entity name, site type, and which resources to expose
Save. Done.

Auto-generated endpoints:

/.well-known/flyweb.json — discovery file
/.flyweb/posts — blog posts as JSONL
/.flyweb/pages — pages as JSONL
/.flyweb/products — WooCommerce products as JSONL

Query parameters:

?category=tech — filter by category
?tag=ai — filter by tag
?price_max=2000 — filter products by max price
?limit=10&offset=20 — pagination

8. Client SDK (for AI agents)

For developers building AI agents that consume FlyWeb-enabled sites:

npm install flyweb

import { discover, fetchResource } from 'flyweb/client';

// Discover what a site offers
const site = await discover('https://example.com');
console.log(site.config.entity);                 // "TechCrunch"
console.log(Object.keys(site.config.resources));  // ["articles"]

// Fetch structured data
const articles = await fetchResource(
  'https://example.com',
  site.config.resources.articles,
  { params: { tag: 'ai' }, limit: 10 }
);

// Respect attribution
if (site.config.attribution?.required) {
  console.log(`Source: ${site.config.entity}`);
}

9. CLI Tool

The FlyWeb CLI works with any website. No install required — just npx.

Check if a site supports FlyWeb:

npx flyweb check https://example.com

Validate a local file:

npx flyweb check ./flyweb.json

Discover and fetch data from a FlyWeb site:

npx flyweb discover https://flyweb.io

Generate a starter config:

npx flyweb init > public/.well-known/flyweb.json

10. Real-World Examples

Blog

{
  "flyweb": "1.0",
  "entity": "Sarah's Tech Blog",
  "type": "blog",
  "url": "https://sarahchen.dev",
  "attribution": { "required": true, "license": "CC-BY-4.0", "must_link": true },
  "resources": {
    "posts": {
      "path": "/.flyweb/posts",
      "format": "jsonl",
      "fields": ["title", "author", "date", "content", "tags"],
      "query": "?tag={tag}&limit={n}",
      "access": "free"
    }
  }
}

E-Commerce (WooCommerce / Shopify)

{
  "flyweb": "1.0",
  "entity": "Glamira Jewelry",
  "type": "ecommerce",
  "url": "https://glamira.com",
  "attribution": { "required": true, "must_link": true },
  "resources": {
    "products": {
      "path": "/.flyweb/products",
      "format": "jsonl",
      "fields": ["name", "price", "currency", "description", "category", "url", "image"],
      "query": "?category={category}&price_max={max}&limit={n}",
      "access": "free"
    },
    "collections": {
      "path": "/.flyweb/collections",
      "format": "json",
      "fields": ["name", "slug", "product_count"],
      "access": "free"
    }
  }
}

Now when someone asks AI "best gold ring under $2000" — your products appear in the answer.

News Publisher

{
  "flyweb": "1.0",
  "entity": "TechCrunch",
  "type": "news",
  "attribution": { "required": true, "license": "CC-BY-NC-4.0", "must_link": true },
  "resources": {
    "articles": {
      "path": "/.flyweb/articles",
      "format": "jsonl",
      "fields": ["title", "author", "date", "section", "summary", "content", "url"],
      "query": "?section={section}&tag={tag}&limit={n}",
      "access": "free"
    },
    "authors": {
      "path": "/.flyweb/authors",
      "format": "json",
      "fields": ["name", "bio", "url"],
      "access": "free"
    }
  }
}

Science / Academic

{
  "flyweb": "1.0",
  "entity": "MIT CSAIL Publications",
  "type": "science",
  "attribution": { "required": true, "format": "{entity}, {url}", "must_link": true },
  "resources": {
    "papers": {
      "path": "/.flyweb/papers",
      "format": "jsonl",
      "fields": ["title", "authors", "abstract", "doi", "date", "keywords"],
      "query": "?keyword={keyword}&author={author}&limit={n}",
      "access": "free"
    }
  }
}

AI cites research with proper attribution. No more hallucinated citations.

API / SaaS Documentation

{
  "flyweb": "1.0",
  "entity": "Stripe Docs",
  "type": "docs",
  "resources": {
    "guides": {
      "path": "/.flyweb/guides",
      "format": "jsonl",
      "fields": ["title", "slug", "content", "category"],
      "query": "?category={category}",
      "access": "free"
    },
    "api-reference": {
      "path": "/.flyweb/api-reference",
      "format": "jsonl",
      "fields": ["endpoint", "method", "description", "parameters", "example"],
      "access": "free"
    }
  }
}

11. FAQ

How is FlyWeb different from JSON-LD / Schema.org?

JSON-LD describes what content IS (a recipe, an article). FlyWeb describes what content you HAVE and how to GET it. FlyWeb is about discovery and access, not semantic annotation. They're complementary.

How is FlyWeb different from llms.txt?

llms.txt is a plain text file with instructions for LLMs. FlyWeb is a structured protocol with machine-readable endpoints, query parameters, attribution, and access controls. FlyWeb gives AI agents actual data, not just instructions.

Do AI agents actually check for flyweb.json?

FlyWeb is designed for the next generation of AI agents. As adoption grows, AI companies are incentivized to check flyweb.json — it gives them cleaner data with less legal risk than scraping. We've filed RFCs with major frameworks to make FlyWeb a default.

Is my private content exposed?

No. You control exactly which resources to expose. Only published, public content is served. Private, draft, or password-protected content is never included.

Can I monetize my content later?

Yes. Start with "access": "free". When payment integration launches, change it to "access": "paid". One line change, no migration.

What about rate limiting?

FlyWeb endpoints are standard HTTP. Use your existing rate limiting, CDN caching, or web server config. The protocol includes Cache-Control headers by default.

← Back to flyweb.io | Full Spec on GitHub | Star on GitHub