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 | Structured plain text with section headers |
| Comments | Lines starting with # are comments |
Basic Structure
# developer-ai.txt for Example Company
# https://example.com/developer-ai.txt
[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.
[public-api]
status: not-available
notes: No public API is currently offered.
[authentication]
User portal requires OAuth 2.0 authentication.
No API keys are issued to third parties.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 |
[public-api] |
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 |
[platforms] |
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 |
[metadata] |
File version and last updated date | 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 [public-api] 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
[public-api]section 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 for Horizon Strategic Consulting
# https://www.horizonconsulting.example/developer-ai.txt
# Last updated: 12 January 2026
[overview]
Horizon Strategic Consulting operates several 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 a content-focused website.
The client portal is a custom application for project management and deliverable access.
[platforms]
www.horizonconsulting.example
- Purpose: Marketing, insights, and public information
- Technology: WordPress with custom theme
- Access: Public
portal.horizonconsulting.example
- Purpose: Client project management and document access
- Technology: React SPA with Node.js backend
- Access: Authenticated clients only (SSO via Azure AD)
api.horizonconsulting.example
- Purpose: Partner integrations
- Technology: REST API (OpenAPI 3.0 documented)
- Access: Approved partners only
[public-areas]
- Marketing website (www) - fully public
- Insights and blog content - fully public
- Service descriptions - fully public
- Client portal - requires authentication
- Partner API - requires approved credentials
[public-api]
status: partner-only
notes: API access is available to approved integration partners only.
No public API registration is available.
Partners must contact partnerships@horizonconsulting.example
[authentication]
Client Portal:
- Method: SSO via Azure Active Directory
- Users: Client employees provisioned by account managers
- No self-registration available
Partner API:
- Method: OAuth 2.0 client credentials flow
- Credentials: Issued upon partner agreement
- Scope: Limited to approved integration use cases
Marketing Website:
- No authentication required for public content
[rate-limits]
Partner API:
- Rate limit: 1000 requests per hour per client
- Burst: 100 requests per minute
- Contact partner support if higher limits required
[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
Marketing site has no public technical documentation.
[technical-contact]
Partner integration enquiries: partnerships@horizonconsulting.example
Technical support for partners: api-support@horizonconsulting.example
General technical enquiries: tech@horizonconsulting.example
[technology-stack]
Note: This information is 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)
[metadata]
version: 1.0
last_updated: 2026-01-12
related_files: [llms.txt](/llms.txt), [ai.txt](/ai.txt), [robots-ai.txt](/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".