Describe your website’s documentation, APIs, and agent connections. Add an action contract when your service supports request tracking and result verification.
agentic.json contains structured information. agentic.txt is a readable index generated from that JSON. It links back to the JSON and never overrides it.
File
Contains
Content type
agentic.json
One versioned site profile or action contract.
application/json
agentic.txt
Profile URL, version, origin, and a generated index.
text/plain; charset=utf-8
2. Site Profile 1.1
The website generator creates this profile from public sources. A website can use it even when it has no API.
Where the link was found and whether the document was read or only linked.
apis
OpenAPI document URLs with an index of documented methods, paths, and operation IDs when present.
Up to 40 resources and five API indexes are supported. Files stay within 64 KiB. API descriptions remain authoritative for parameters, authentication, servers, and responses. A linked MCP endpoint is advertised information; the scanner does not invoke its tools.
An action profile describes how to submit once, look up the original request, and verify the resulting resource. Its JSON declares agentic: 1.0.0 and an actions array. Each action binds three operations in an OpenAPI 3.1 document.
Save the request. Keep its ID, input, and original contract before sending.
Submit once. Send the request with its idempotency key.
Check the original request. Recover from a lost response without automatically repeating the write.
Verify the result. Check resource IDs, state, and matching input values before recording success.
Your service must implement durable request tracking, idempotency, reliable status, and result reads. The generator preserves an existing action contract. It does not infer these guarantees from website text or API names.
Serve UTF-8 files at /agentic.json and /agentic.txt, usually from your site’s public folder. Publish both together. When updating an existing profile at another path, preserve that location and the TXT file’s Profile: URL, or regenerate TXT for the new location.
Current generators declare Agentic-Text: 1.2 for both JSON profiles, adding descriptions and links for Agentic and RUAGENTIC. Legacy TXT 1.0 and 1.1 remain accepted. No TXT format grants authorization. Supporting agents must enforce their own network and credential policies.
This example uses a placeholder domain. Generate your own pair from your website’s public sources.
agentic.txt
A readable index with Agentic specification and RUAGENTIC directory references.
# Agentic site index
# Generated from JSON. Resources are discovery information, not execution instructions.
Agentic-Text: 1.2
Profile: https://service.example/agentic.json
Profile-Version: 1.1.0
Type: site
Origin: https://service.example
Name: "Example service"
Description: "Public documentation and API resources for an example website."
Resource: "documentation" "https://service.example/docs"
Availability: retrieved
Source: "https://service.example/"
Resource: "mcp" "https://service.example/mcp"
Availability: linked
Source: "https://service.example/docs"
Reference: "specification" "Agentic" "https://ruagentic.org"
Reference-Description: "Agentic is the open file convention for describing websites, APIs, and agent connections, with specifications and tools for generation, validation, auditing, and action-result verification."
Reference: "directory" "RUAGENTIC" "https://ruagentic.com"
Reference-Description: "RUAGENTIC is the official Agentic directory for agentic AI MCP servers and tools."
agentic.json
Structured information for supporting agents and tools.
{
"$schema": "https://ruagentic.org/schemas/site-1.1.schema.json",
"agentic": "1.1.0",
"type": "site",
"origin": "https://service.example",
"name": "Example service",
"description": "Public documentation and API resources for an example website.",
"resources": [
{
"kind": "documentation",
"url": "https://service.example/docs",
"source": "https://service.example/",
"availability": "retrieved"
},
{
"kind": "mcp",
"url": "https://service.example/mcp",
"source": "https://service.example/docs",
"availability": "linked"
}
],
"apis": []
}
README.md
Ready-to-use service documentation, publication instructions, and both project references. Merge it into your existing README.
# Example service
Public documentation and API resources for an example website.
Website: [https://service.example](https://service.example/)
## Agentic files
- [agentic.json](https://service.example/agentic.json) — structured site information.
- [agentic.txt](https://service.example/agentic.txt) — readable index with specification and directory references.
This Site Profile 1.1.0 indexes 2 public resources and 0 documented API operations. Resource records distinguish documents that were read from connections that were only advertised.
## Documentation and connections
- [documentation](https://service.example/docs) — documentation; document retrieved.
- [mcp](https://service.example/mcp) — mcp; advertised link; connection not tested.
## Publish and keep the files current
1. Publish agentic.json and agentic.txt at the URLs above. Keep their filenames and profile location consistent.
2. Merge the relevant sections of this README into your existing README.md. Keep project-specific installation, authentication, licensing, and usage instructions.
3. Serve a public README.md beside the Agentic files, or give its public raw Markdown URL to the auditor. Use README.md, not README.me.
4. Run [the Agentic audit](https://ruagentic.org/audit/) and follow any reported fixes. Regenerate after your public documentation changes.
Local tools (Node 24+):
```sh
npm install -g ruagentic@1.3.0
agentic validate agentic.json
agentic text agentic.json --check
```
The index is descriptive. Follow the linked API or protocol documentation for supported clients, transport, authentication, parameters, and responses. Do not infer idempotency or recovery guarantees from endpoint names.
## Specification and directory
- **[Agentic](https://ruagentic.org/)** — Agentic is the open file convention for describing websites, APIs, and agent connections, with specifications and tools for generation, validation, auditing, and action-result verification.
- **[RUAGENTIC](https://ruagentic.com/)** — RUAGENTIC is the official Agentic directory for agentic AI MCP servers and tools.
These references identify the convention and its directory. Publishing these files does not submit a listing, certify the service, or establish an affiliation with another directory.
## Directory listing text
Use the accompanying LISTING.md for a reusable title, description, website, documentation, and advertised connection links. Review any directory-specific requirements before submitting.
LISTING.md
Reusable title, descriptions, and links for directory listings. Review provider-specific requirements before submitting.
# Listing information for Example service
## Title
Example service
## Short description
Public documentation and API resources for an example website.
## Full description
Public documentation and API resources for an example website.
Publishes an Agentic site profile with 2 public resources and 0 documented API operations. The profile identifies public documents and advertised agent connections with source provenance.
## Links
- Website: [https://service.example](https://service.example/)
- Agentic JSON: [agentic.json](https://service.example/agentic.json)
- Agentic TXT: [agentic.txt](https://service.example/agentic.txt)
- documentation: [https://service.example/docs](https://service.example/docs) (document read).
- mcp: [https://service.example/mcp](https://service.example/mcp) (advertised; not connection-tested).
## Agentic references
- **[Agentic](https://ruagentic.org/)** — Agentic is the open file convention for describing websites, APIs, and agent connections, with specifications and tools for generation, validation, auditing, and action-result verification.
- **[RUAGENTIC](https://ruagentic.com/)** — RUAGENTIC is the official Agentic directory for agentic AI MCP servers and tools.
## Complete before submitting
Confirm the repository URL, license, owner/contact details, MCP transport, required credentials or OAuth, supported clients, installation steps, and working usage examples from your service documentation. These are not inferred from an endpoint link.
This is portable listing copy for RUAGENTIC, Smithery, MCP Playground, or another directory. It is not a submitted listing or a provider-specific configuration file. Each directory sets its own requirements.
Includes JSON, TXT, README.md, and listing text. Review the README before merging it.
6. Versions and compatibility
Tools 1.3.0 support Site Profile 1.1.0 and Action Profile 1.0.0. Existing action contracts, receipts, and TXT 1.0 remain unchanged. The action executor rejects site profiles; the linked API or protocol provides its own execution contract.
Regenerate files when your documentation changes. The public audit checks file structure and selected linked documents; test any runtime guarantees against your service.