This specification is published and recommended for implementation. Backwards-compatible additions may occur in MINOR versions; breaking changes only in MAJOR versions, with deprecation notice. See specification conventions for status definitions.
developer-ai.txt Specification
Technical Context File Format for AI Systems
This specification defines the structure and requirements for developer-ai.txt files: plain text files that provide technical context for AI systems. The file describes platforms, APIs, authentication requirements, and integration capabilities, helping AI systems that assist developers understand the technical landscape of a website or service.
§1 Overview
What This File Does
The developer-ai.txt file provides technical context for AI systems that need to understand a website's technical infrastructure. It describes:
- Platforms and technology stack (at a high level)
- Public vs. private areas
- API availability and access methods
- Authentication requirements
- Integration capabilities and limitations
Why It Matters for AI Visibility
AI coding assistants increasingly help developers integrate with third-party services. Without technical context, AI systems may:
- Suggest integrations that don't exist
- Provide outdated API information
- Miss authentication requirements
- Confuse public and private endpoints
A developer-ai.txt file provides authoritative technical context.
Use Case
This file is primarily useful for AI systems helping developers who want to:
- Integrate with the organisation's services
- Understand the technical architecture
- Find relevant API documentation
- Understand what's publicly accessible vs. restricted
This file provides context, not comprehensive documentation. It SHOULD point to detailed documentation rather than duplicate it.
§2 File Location
Primary Location
The developer-ai.txt file MUST be placed in the website's root directory:
https://example.com/developer-ai.txtURL Requirements
- The file MUST be served with content type
text/plain; charset=utf-8 - The URL MUST be accessible without authentication
- HTTPS is strongly recommended
§3 Format Specification
File Format
| Property | Requirement |
|---|---|
| Encoding | UTF-8 (required) |
| Line endings | LF (Unix-style) recommended; CRLF accepted |
| Syntax | Markdown-style headings in plain text (one H1 title, H2 section headings) |
| Comments | Lines beginning with # above the H1 heading are comments |
Basic Structure
# Technical Context - Example Company
Lang: en-GB
Website: [https://example.com](https://example.com)
Last Updated: 2026-01-12
## Overview
Example Company provides a SaaS platform for project management.
The main marketing site runs on WordPress.
The application is a React-based SPA with a Node.js backend.
## API Information
Status: not-available
No public API is currently offered.
## Authentication
User portal requires OAuth 2.0 authentication.
No API keys are issued to third parties.Earlier revisions of this specification described sections as bracketed headers ([overview]). H2 headings are now the documented form, matching the reference implementation and the published templates. Consumers SHOULD accept either form; the reference validator does.
Markdown Hyperlinks for URLs
When referencing documentation, tools, resources, or external URLs, use markdown hyperlink format rather than plain URLs:
## Documentation
- [API Reference](https://api.example.com/docs)
- [SDK for Python](https://github.com/example/python-sdk)
- [Authentication Guide](https://docs.example.com/auth/)- Use the format
[Link Text](url)for all resource links - The link text SHOULD describe what the resource is, not just repeat the URL
- This gives AI systems anchor text context about each link's purpose
- Plain URLs are accepted but markdown hyperlinks are RECOMMENDED
AI coding assistants that consume developer-ai.txt can extract both the description and URL from markdown links. When a developer asks "where are the API docs?", the AI can provide a labelled, contextual link: not just a raw URL. This improves the quality of AI-generated developer guidance.
Language declaration (optional)
Publishers MAY declare the natural language of the file's human-readable content using a Lang: header line near the top of the file (above the first bracketed section). The value MUST be a valid BCP 47 language tag:
Lang: en-GBThe header is optional. When absent, consumers SHOULD NOT assume a default language. When present, validators MUST treat the value as informational and MUST NOT fail conformance solely on language-tag content. See specification conventions §5.1 for the full rule, which is identical across every text-based AI Discovery File.
§4 Section Reference
Required Sections
| Section | Description | Status |
|---|---|---|
## Overview |
High-level technical description of the platform | Required |
## API Information |
API availability (available, not-available, partner-only) | Required |
## Public Areas |
Which parts of the site/service are publicly accessible | Required |
Recommended Sections
| Section | Description | Status |
|---|---|---|
## Authentication |
Authentication methods and requirements | Recommended |
## Platform |
Different platforms/subdomains and their purposes | Recommended |
## Documentation |
Links to technical documentation | Recommended |
## Technical Contact |
Contact for technical or integration queries | Recommended |
Optional Sections
| Section | Description | Status |
|---|---|---|
## Technology Stack |
Technologies used (where relevant to integrations) | Optional |
## Rate Limits |
Rate limiting policies if APIs exist | Optional |
## Webhooks |
Webhook capabilities and endpoints | Optional |
## SDKs |
Official SDKs, libraries, or client packages available | Optional |
## Integrations |
Pre-built integrations with third-party platforms | Optional |
## Sandbox |
Test/sandbox environment availability and access | Optional |
## AI Discovery Files |
Links to the other AI Discovery Files published on the same host | Optional |
## Data Feeds |
RSS, Atom, or other machine-readable content feeds | Optional |
## Developer Notes |
Free-text notes for developers and AI coding assistants | Optional |
Content Not Permitted
The following content types MUST NOT be included in developer-ai.txt files:
- Credentials: Never include API keys, secrets, passwords, or tokens
- Internal URLs: Do not expose internal hostnames, IP addresses, or infrastructure details
- Security vulnerabilities: Do not detail security measures in ways that aid attackers
- Unreleased features: Only document publicly available capabilities
- Deprecated endpoints: Remove references to discontinued APIs unless clearly marked as deprecated
- Customer data patterns: Do not include examples that reveal customer data structures
Public API Section Values
The ## API Information section SHOULD include a status line using one of these values:
| Status | Meaning |
|---|---|
available | Public API available to anyone |
partner-only | API available but requires partnership/approval |
not-available | No public API offered |
deprecated | API exists but is being discontinued |
§5 Validation Rules
Valid File Requirements
A developer-ai.txt file is considered valid when:
- It contains the three required sections
- The
## API Informationsection includes a status declaration - The file is valid UTF-8 encoded text
- URLs to documentation are valid and accessible
Common Errors
| Error | Resolution |
|---|---|
| Missing API status | Add explicit status line (available, not-available, etc.) |
| Broken documentation links | Verify all URLs are current |
| Outdated technology info | Review when major platform changes occur |
| Security-sensitive details | Only include publicly appropriate information |
§6 Relationship to Other Files
Related AI Discovery Files
| File | Relationship |
|---|---|
llms.txt |
May link to developer-ai.txt for technical context |
ai.txt |
Permissions for how AI SHOULD use technical info |
robots-ai.txt |
Crawler access rules; developer-ai.txt is about usage context |
Relationship to robots.txt
The developer-ai.txt file provides usage context while robots.txt controls crawler access:
robots.txt: Can AI crawlers access pages?developer-ai.txt: What is the technical context for integration?
For complete conflict resolution rules, see the Interoperability Guide.
§7 Canonical Example
The following example demonstrates a complete developer-ai.txt file:
# developer-ai.txt Specification (ADF-009)
# https://www.ai-visibility.org.uk/specifications/developer-ai-txt/
# Technical Context - Horizon Strategic Consulting
Lang: en-GB
Website: [https://www.horizonconsulting.example](https://www.horizonconsulting.example)
Last Updated: 2026-01-12
## Overview
Horizon Strategic Consulting operates three web properties:
- Marketing website (www.horizonconsulting.example): public content
- Client portal (portal.horizonconsulting.example): authenticated access
- Partner API (api.horizonconsulting.example): restricted access
The marketing site is content-focused. The client portal is a custom application
for project management and deliverable access.
## Platform
- CMS: WordPress with a custom theme
- Application: React SPA with a Node.js backend
- Character Set: UTF-8
- Language: en-GB
## Public Areas
- Marketing website: fully public
- Insights and blog content: fully public
- Service descriptions: fully public
- Client portal: requires authentication
- Partner API: requires approved credentials
## API Information
Status: partner-only
API access is available to approved integration partners only. There is no public
API registration. Partners should contact partnerships@horizonconsulting.example.
## Authentication
Client portal:
- Method: SSO via Azure Active Directory
- Users: client employees provisioned by account managers
- No self-registration
Partner API:
- Method: OAuth 2.0 client credentials flow
- Credentials: issued on signature of a partner agreement
- Scope: limited to approved integration use cases
Marketing website: no authentication required for public content.
## Rate Limits
Partner API:
- 1000 requests per hour per client
- Burst: 100 requests per minute
- Contact partner support if higher limits are required
## Technology Stack
Provided for context only.
- Marketing site: WordPress, PHP, MySQL
- Client portal: React, Node.js, PostgreSQL
- Partner API: Node.js, Express, PostgreSQL
- Hosting: cloud-based (AWS)
## Documentation
- [Partner API Reference](https://api.horizonconsulting.example/docs): OpenAPI 3.0 specification, authentication guide, and endpoint reference (approved partners only)
- [Status Page](https://status.horizonconsulting.example/): real-time system status and incident history
The marketing site has no public technical documentation.
## Developer Notes
The marketing site and the client portal share no code and no session state. Content
published on the marketing site is safe to cite; anything behind portal.horizonconsulting.example
is client-confidential and must not be retrieved or summarised.
## Data Feeds
- [RSS](https://www.horizonconsulting.example/feed/)
- [Atom](https://www.horizonconsulting.example/feed/atom/)
## Technical Contact
- Partner integration enquiries: partnerships@horizonconsulting.example
- Technical support for partners: api-support@horizonconsulting.example
- General technical enquiries: tech@horizonconsulting.example
## AI Discovery Files
- [llms.txt](https://www.horizonconsulting.example/llms.txt)
- [ai.txt](https://www.horizonconsulting.example/ai.txt)
- [ai.json](https://www.horizonconsulting.example/ai.json)
- [identity.json](https://www.horizonconsulting.example/identity.json)
- [brand.txt](https://www.horizonconsulting.example/brand.txt)
- [faq-ai.txt](https://www.horizonconsulting.example/faq-ai.txt)
- [robots-ai.txt](https://www.horizonconsulting.example/robots-ai.txt)§8 Implementation Notes
Best Practices
- Be explicit about what is NOT available (no public API, no self-registration)
- Include contact information for technical queries
- Link to documentation rather than duplicating it
- Use markdown hyperlinks
[Link Text](url)for all resource references - Update when platforms or APIs change
- Don't include security-sensitive configuration details
Security Considerations
- Only include publicly appropriate technical information
- Don't expose internal IP addresses or hostnames
- Don't include API keys, secrets, or credentials
- Don't detail security measures in ways that aid attackers
- Focus on what's available, not how it's secured
Who Should Use This File
This file is most valuable for organisations that:
- Have developer-facing services or APIs
- Want to clarify what's publicly accessible
- Receive technical integration queries
- Need to prevent AI from suggesting non-existent integrations
§9 Machine-Readable Formats
This specification is available in machine-readable formats for programmatic access:
§10 Version History
Phase 6 standardisation release. Added /specifications/roadmap/ (theme-pegged forward plan with Active/Next/Future/On hold status flags), /specifications/extensions/ (rules for experimental x- prefixed files and the promotion path), and /specifications/i18n-a11y/ (multi-language publication, locale-tagged identity fields, RTL handling, accessibility of llms.html). Added the Discovery: directive to the robots-ai.txt specification (publishers MAY advertise AI Discovery Files on the same host). Added a formal media-type stance to the HTTP behaviour page (existing IANA types, no bespoke registrations). Expanded the file integrity and signing section on the security and privacy page with four candidate mechanisms, cross-cutting concerns, and interim publisher / consumer guidance. The Discovery: directive is the only normative addition to publisher behaviour; all other additions are forward-looking documentation.
Phase 5 standardisation release. Added /specifications/related-standards/ (positioning vs llmstxt.org, IETF AI Preferences, robots.txt, Schema.org, BCP 14, JSON Schema 2020-12, SemVer) and /specifications/implementations/ (public record of conformant implementations, IETF-style). Added an explicit llmstxt.org backward-compatibility statement to the llms.txt specification. Added a formal multi-domain and subdomain scoping rule to both the llms.txt and identity.json specifications (host-scoped files, cross-host identity asserted via sameAs). No normative requirements changed for existing publishers; the new scoping rules formalise behaviour the specification already implied.
Phase 4 standardisation release. Added /specifications/processing-model/ (seven-stage algorithm for conformant consumers), /specifications/consumer-guidance/ (what AI systems should do with AI Discovery Files), /specifications/test-vectors/ (canonical test suite framing), and reference-implementation framing on the AI Visibility Checker. No normative requirements changed.
Phase 3 standardisation release. Added /specifications/versioning/ (Semantic Versioning 2.0.0 commitments, deprecation timeline, lifecycle), /specifications/governance/ (proposal lifecycle, editorial process, working principles), /specifications/security-privacy/ (trust model, content-injection patterns, GDPR considerations, integrity primitives roadmap), and /specifications/http-behaviour/ (status codes, redirects, soft-404 detection, caching, rate limits). No normative requirements changed.
Phase 2 standardisation release. Added formal conformance specification (Essential / Recommended / Complete classes). Published machine-readable registry at /specifications/registry.json, spec meta-schema, and validator-output schema. Introduced versioned JSON Schema URLs (/v1/) alongside unversioned 'latest' aliases. Added optional BCP 47 language declaration field across all applicable AI Discovery Files. No normative requirements changed.
Phase 1 standardisation release. Added 'Status of This Document' block (Stable). Normalised normative requirement keywords to uppercase per RFC 2119 and RFC 8174. Added References section linking to /specifications/conventions/ and /licensing/. No normative requirements changed.
Added guidance to use markdown hyperlink format [Link Text](url) for documentation links, resource lists, and related file references. Helps AI coding assistants provide labelled, contextual links. Updated canonical example to demonstrate the pattern.
Added AI Visibility Directory registration guidance. Minor documentation update.
Added expanded optional sections (sdks, integrations, sandbox) and Content Not Permitted guidance. Emphasises security considerations for technical documentation.
Initial publication. Establishes canonical structure for developer-ai.txt files with technical context for AI systems.
Conformance
This file is required for the Complete conformance class only. A publisher claiming Complete conformance MUST publish a valid version of this file at the website's root. The Essential and Recommended classes do not require this file.
See the Conformance specification for full publisher and validator conformance criteria, including identity-consistency requirements across files and the relationship between self-declaration and Directory verification.
References
- Specification Conventions: RFC 2119 + RFC 8174 requirement keywords, document statuses, anchor naming, versioning, and language conventions used across every AI Discovery File specification.
- Licensing & Trademark: CC BY 4.0 for specification text and examples, MIT for JSON Schemas, and the free-use policy on the name "AI Discovery Files".