What an API provider says about AI: whether its content and API output may be used to train AI or generative AI, used for AI inference or search, and whether an AI agent may sign up, act, or buy on a person's behalf — plus whether it publishes machine signals (an AIPREF header, Content Signals, ai.txt, llms.txt). As agents become API consumers, this is the part of the terms they have to be able to read.
This is the schema behind the AI Preferences property in API Commons.
API Commons was started to make the business side of API onboarding machine-readable. Finding an API is the easy part; deciding whether you are allowed to use it — for this purpose, in this country, with this data, by this kind of client — still means a person reading legal pages. When the answer is a document a crawler, a catalog or an agent can read, discovery and onboarding can be automated end to end, and a consumer can compare providers on the terms rather than on the marketing.
- ai-preferences-json-schema.yml — the JSON Schema (2020-12).
- ai-preferences-example-1.yml — a standalone document, as written to
all/<slug>/ai-preferences/<slug>-ai-preferences.yml. - ai-preferences-example-2.yml — the same document inside the
AIPreferencesapis.yml property envelope. - validate.py — validates any document against the schema.
Both examples describe Example Weather API, a fictional provider. The clauses are illustrative and are not the terms of any real company.
Every document carries the common envelope:
ai_preferences: 0.1.0
provider: Example Weather API
aid: example-weather-api
url: <the page it was read from>
source_date: YYYY-MM-DD
x-apis-io-derivation:
synthetic: false
method: harvested
read: YYYY-MM-DD
tool: engine/business/harvest-business.py
model: <model id>and then:
| Field | Shape | Meaning |
|---|---|---|
train_ai |
{stance, text} |
Training any AI model on the provider's content or API output (AIPREF train-ai). |
train_genai |
{stance, text} |
Training generative AI models (AIPREF train-genai). |
ai_use |
{stance, text} |
Using content in AI inference or AI search (AIPREF search / Content Signals ai-input). |
agent_onboarding |
{stance, text} |
An AI agent signing up or obtaining credentials on a person's behalf. |
agent_actions |
{stance, text} |
An AI agent calling the API to act on a person's behalf. |
agent_purchases |
{stance, text} |
An AI agent making purchases or incurring charges on a person's behalf. |
signals |
{aipref_header, content_signals, ai_txt_url, llms_txt_url} |
From HTTP probes only, never the model |
Wherever a permission is described: allowed | prohibited | conditional | unstated. Every stance other
than unstated must carry a verbatim text — the schema enforces it. unstated means the page says
nothing, which is a valid, recorded result and is never filled in with a guess. Periods ("30 days",
"12 months") are copied as written and never normalized.
Only documents read from the provider's own page are published. There is no template fill. The page is
fetched by code; a model only transcribes rows from it; every row's text is checked word for word
against the fetched page and dropped if it does not match. x-apis-io-derivation.synthetic is always
false and method is always harvested — the schema rejects anything else.
Sources (apis.yml property types): AIPolicy, AITerms, AIPREF, AITxt, plus the same terms-of-service page fetch.
The IETF AIPREF vocabulary for AI usage preferences and Cloudflare's Content Signals, plus the ai.txt and llms.txt files. The train_ai, train_genai and ai_use keys follow the AIPREF categories; the three agent_* keys extend them to agents acting on an API.
pip install jsonschema pyyaml
python3 validate.py ai-preferences-example-1.yml ai-preferences-example-2.yml
Exits non-zero on any failure, so it can gate a pipeline.
Two licenses, by kind of thing:
- Artifacts — the schemas and examples — are CC BY-NC-SA 4.0 (Attribution–NonCommercial–ShareAlike).
- Code — the validator — is Apache-2.0.
A machine-readable building block from API Commons. Related business-layer blocks: terms-of-service · privacy-policy · deprecation-policy · compliance · eligibility · ai-preferences · data-license · service-level-agreement · plans · rate-limits