Most of RolesAPI’s users are not people reading a browser. They are AI agents: coding assistants wiring up a job-data pipeline, research agents comparing salaries across markets, and autonomous workflows that watch for new postings. That changes what “being discoverable” means. A human finds an API through a search result and a landing page. An agent needs a machine-readable trail it can follow from nothing but a domain name to an authenticated session.
This post documents the full trail as it exists on rolesapi.com today. Everything below is live and verifiable with the commands shown.
Step 1: DNS answers the first question
The newest layer is DNS for AI Discovery (DNS-AID), an IETF draft that gives agents a well-known entry point in the DNS itself. We publish two ServiceMode SVCB records under the _agents namespace:
_index._agents.rolesapi.com. 300 IN SVCB 1 api.rolesapi.com. mandatory=alpn,port alpn="mcp" port=443_mcp._agents.rolesapi.com. 300 IN SVCB 1 api.rolesapi.com. mandatory=alpn,port alpn="mcp" port=443An agent that knows nothing except “rolesapi.com” can issue one DNS query and learn that an MCP endpoint lives at api.rolesapi.com on port 443. The zone is signed with DNSSEC and the DS record is published at the registrar, so validating resolvers return these answers with the authenticated data flag set. You can check it yourself:
dig @1.1.1.1 SVCB _index._agents.rolesapi.com +dnssecStep 2: well-known endpoints describe the service
Once an agent knows where to look, the standard well-known surfaces fill in the details:
/.well-known/api-cataloglists the API as an RFC 9727 linkset./.well-known/mcp/server-card.jsondescribes the MCP server, its transport, and its tools./.well-known/agent-skills/index.jsonpublishes agent skills with content digests./openapi.jsonis the full OpenAPI 3.1 contract, served with the openapi media type.
The same links are exposed as RFC 8288 Link relations in both HTTP response headers and HTML, so an agent can find them without parsing a page body.
Step 3: llms.txt explains it in prose
For agents that read text rather than structured metadata, /llms.txt is a compact map of the whole site and /llms-full.txt is the entire documentation corpus in one file, including our FAQ. Both are regenerated from the documentation source on every build, so they cannot drift from the published pages. Our server logs show IDE agents and MCP clients fetch these files daily.
Step 4: OAuth 2.1 gets the agent a key
Discovery ends at authentication. The MCP server at https://api.rolesapi.com/mcp accepts OAuth 2.1 with PKCE, advertised through RFC 8414 authorization server metadata and RFC 9728 protected resource metadata. An agent platform like Claude can walk this chain with no human in the loop beyond a consent screen. Agents that already hold an rk_ API key can skip OAuth and send it as a bearer token.
Step 5: the session itself
After the handshake, the agent has five tools: search_roles, get_role_by_key, get_role_by_url, get_salary_info, and get_role_description. Every answer costs one credit and comes back as the same normalized role object the REST API returns.
Why we publish all five layers
No single layer is universally adopted yet. Google has said llms.txt is not a ranking input, DNS-AID is still an IETF draft, and MCP adoption is growing fastest inside developer tools. Publishing every layer costs little and means an agent can reach us through whichever mechanism its platform implements. The scanner at isitagentready.com now validates all of it, including the DNSSEC chain.
If you are building an agent that needs live job-postings data, the shortest path is the AI agents guide. If you want the same discovery stack on your own API, the changelog tracks how each piece landed here.