Every enterprise AI integration today secretly bottoms out at the same thing: a human encoding API knowledge into a bespoke connector that will drift, break, and need to be rewritten. This demo is built on a fundamentally different premise... and the difference matters enormously.
The standard playbook for connecting AI to enterprise software goes like this: write a custom MCP server, or define function-calling tools by hand; hardcoded field names, hardcoded URLs, handwritten descriptions the model will try to interpret. Do that for every API you want the agent to reach.
The model only knows what you told it at build time. When the API changes, the agent breaks silently... or worse, hallucinates confidently about endpoints that no longer exist. Each connector is an island. The agent can't reason across systems because there's no shared vocabulary connecting them. And nothing about this approach scales: every new API is another bespoke connector to write, maintain, and keep synchronized with whatever knowledge is buried in the model's context.
This is the integration tax. Every enterprise AI project pays it. Most teams have simply accepted it as the cost of doing business with AI.
What if the API told the agent what it could do? Not in a README no agent can parse but in a machine-readable vocabulary, served live at a discoverable URL, that a generic client can consume and act on with zero prior knowledge of that specific API.
This is exactly what Hydra is: a W3C community vocabulary for self-describing Web APIs. Using JSON-LD, a Hydra-compliant API publishes an ApiDocumentation that declares the resource types it manages, the HTTP operations supported on each, the properties of those resources (with readable, writable, and required flags and semantic IRIs), and structured URL templates for filtered queries. The API is its own documentation, and that documentation is machine-readable by design and, more importantly, natively machine-understandable. This is the true secret sauce, semantics, not syntax.
These aren't new ideas invented for AI. They are established W3C and IETF standards, built over two decades to give machines enough context to act on information without a human in the loop to interpret it. The insight here is applying them as the native interface layer for autonomous AI agents.
The semantic web was built for exactly this moment.
The Hydra client in this demo is a deterministic hypermedia runtime. The language model never sees an HTTP method or an authorization header, and never constructs a URL — it can't exfiltrate your token, and the addresses it uses are ones the API's own documents handed it, copied and never composed. It holds a small set of constant controls — follow, search, read, invoke, query — and everything this API can do arrives as content: a collection index rendered into its instructions at connect, and the affordances each result carries. The model browses; it does not memorise a surface. Here is exactly what happens:
You supply a single URL: the API entry point. The client fetches it and reads the response's Link header, where the server advertises where its ApiDocumentation lives. It does not append /Vocab to anything. That distinction is the whole hypermedia principle in one step: if the server moved its vocabulary tomorrow, the client would follow it there without a change, because it never knew the old address either. Serve that header from a path nothing could guess and the client still finds it; remove the header and it refuses to guess, by name, rather than silently probing.
The vocabulary declares every resource type, every supported operation with its expected and returned types, every property with read/write/required flags, and IriTemplates for filtered queries. From there the client follows further pointers the same way: to the SHACL shapes graph, to each @context document, to a SPARQL endpoint if one is advertised. Everything retrieved is parsed into one RDF graph and nothing above that layer ever sees JSON again. Two documents spelling the same term differently, one compact and one expanded, land on the same node.
Classes, operations, properties, templates, collections and their member types are read out of the graph rather than walked as a JSON tree, then joined to the SHACL property shapes on the RDF predicate IRI. Reading it as data is what makes the answer independent of how the server chose to serialise it. Against this API that comes out as 27 classes, 10 collections, 38 operations and 22 templates — none of it configured anywhere.
Each declared operation and template becomes a registry record — a stable handle, an input contract generated from the SHACL constraints, the vocabulary's own prose carried verbatim (the paragraph explaining that PUT replaces rather than merges is exactly what stops a model mangling an update). The model itself holds five constant tools, identical for every Hydra API: follow, search_collection, get_resource, invoke, sparql. Capability scales in what the results say, not in how many tools exist — a vocabulary of any size projects the same controls. The registry and the index are the only things the model ever sees about the API. Not HTTP methods. Not auth headers. The index does carry one thing that looks like a URL — each collection's resolved address — but as a value to copy, never a pattern to fill in, and the model still composes none of its own. That same index names every write the API declares, each labelled by what it does (POST creates, PUT replaces, DELETE deletes), and states plainly that it is complete: browsing never turns up a capability the index did not already list, so “can this API do X?” is answered by reading, not by probing. Point the client at a different Hydra API and the affordances change with no code change, which is a claim the test suite checks against a vocabulary for an API that does not exist.
Your message goes to the model with the constant controls attached and the collection index in its instructions, and it calls tools directly through the provider's native tool-use protocol — no intermediate plan format invented on top of one that already exists. The controls divide the work by how much they promise: follow reads a single page and states honestly how much of the collection it left behind; search_collection is the deliberate one, traversing a filtered set to its end; and a count or a total is never read off a listing but sent to sparql, which answers where the data is whole and returns only the number. Every result ends with the affordances of what it holds: the write operations it can invoke (as handles with their contracts), the filters the collection declares, pagination state. A listing teaches the filter that would have avoided it; a resource offers its own edit. Never raw HTTP. Never a URL it constructed. And because the controls are constant, no affordance is ever deferred, truncated, or silently dropped — discovery cannot fail.
Each call becomes real HTTP: RFC 6570 templates expanded, hydra:Link references resolved through their declared range, and — when the call asked for the whole set rather than a single-page follow — hydra:next followed to the end of the collection with no page ceiling. Any published constraint the tool schema could not carry is checked here first, and a value that violates one is refused with the constraint quoted and no request issued at all. A write reads the current representation from the origin first, always — a replacement built from a cached copy silently reverts every field someone else changed in the meantime.
After every update the client compares what the server echoed back against what was sent, statement by statement in the graph rather than key by key — so a server that stored your value under a differently spelled name is still seen to have kept it, and one that quietly dropped it is still seen to have dropped it. A 200 OK is not proof anything stuck. The agent's job is to tell you what actually happened, not what it expected to happen.
Almost no API publishes all four documents on day one, and a client that demanded them all would prove nothing portable. So this one detects what is actually there, tells you which rung you are on, and degrades at a named layer rather than either failing or quietly doing less. Connect it to your own API and the badge in the sidebar is a roadmap: it says what you publish today, and what publishing the next document would buy you.
Operations, HTTP methods, required fields, declared status codes and the API's own descriptions. That alone is enough to project a working toolset and act on it. Everything above this rung makes the agent more precise; nothing above it is needed to make it function.
@context — keys stop being guesses
Payload keys resolve to IRIs, including nested ones, so the client knows what a field means rather than what it is spelled. Note the word valid: a context that is served but malformed buys no tier at all, because no conformant processor can expand anything that references it. Reachable is not the same as usable, and the client will tell you which one you have.
Datatypes, formats, and value sets that reach the affordance contracts the model reads — and where a property points at a class a read-only reference collection serves in full, the collection's live members become the value set, enforced before dispatch. Every published constraint is checked at the gate before a request is spent, and a violation is refused with the constraint quoted. This is the rung where a bad write stops costing you a request.
Subclass closure, and aggregate questions answered by the endpoint over the whole dataset instead of locally over what was fetched. Reachable is doing real work in that sentence: an advertised endpoint is a claim, so the client probes it and believes the probe. And reachable is not the same as synchronised: an endpoint that answers but holds a different count than the API declares is stale, and rather than trust a mirror that has drifted the client falls through to the complete local path — the divergence recorded as provenance on the answer, so the reader can see which dataset replied. This deployment has advertised an endpoint that was live and one that was dead without changing the advertisement.
Analytics do not wait for T3. Ask “how much did I make last year” against an API with no SPARQL endpoint at all and the client works out which collections the question is scoped to — through the declared member types, never by guessing from names — fetches them completely, and runs the query locally over the graph it built.
Two rules make that answer trustworthy rather than merely fast. Every term in the query must be one the API declares, checked before anything executes: an invented predicate against a live endpoint does not error, it returns zero rows, and a confident wrong total is worse than a refusal. And an aggregate runs only over a set proved complete — every page fetched, and every field it touches one the collection actually serves. Otherwise it declines and says what is missing. A sum over most of your data is not a smaller answer; it is a wrong one.
This isn't an incremental improvement on bespoke connectors. It's a different category of solution. Here's what it eliminates:
hydra:freetextQuery for relevance-ranked results. No per-API query syntax to document or learn. A binding has to be an IRI to carry that meaning — where a template variable is published as a plain string it names nothing, and the client reports precisely that rather than inferring the variable's purpose from its spelling.
hydra:next links declared in each response; the semantically correct way to traverse a collection. No URL pattern assumptions. No page-number math baked into the agent. No page ceiling either — a cap would hand you 250 of 3,000 records as though that were the answer. The server controls how its collections are navigated, and where a collection stops linking without declaring a pagination route, that is reported as a gap in the API rather than papered over with a guessed address.
@context, so wire keys are correct by construction.
hydra:Link with a formal range derived from the OWL ontology at the point the vocabulary is generated. The client resolves the reference by traversing that declared relationship. It never guesses from field names, string patterns or English morphology — a collection is matched to its member type through the declared range, never by singularising its name. Where the range is missing, the client does not quietly drop the field: it says which property is undeclared, what publishing the range would unlock, and which routes remain open in the meantime.
This demo is a proof of concept for a specific claim: a standards-based semantic layer can be the native interface between AI agents and enterprise software. Not bespoke connectors. Not per-API tool definitions curated and maintained by hand. A uniform, self-describing, machine-readable contract that any compliant API can publish and any compliant client can discover and act on automatically.
The implications go further than a single API. Hydra's Linked Data foundation means that connections between systems aren't point-to-point integrations, they're edges in a graph. A contact who works at a company that has booked an event isn't three separate silos requiring three separate connectors. It's a traversable subgraph. An agent reasoning over it can follow those typed links across system boundaries, the same way a browser follows hyperlinks across domains; declaratively, without prior knowledge of the topology.
This is the architecture for enterprise AI that actually scales. Not more connectors. Not bigger context windows stuffed with API documentation. A semantic layer that lets agents discover and operate on enterprise data the way the Web lets humans navigate information through structure, through links, through self-describing resources that carry their own meaning.
Hydra covers what REST clients need. HydrAI —a proposed extension to the Hydra vocabulary —adds what autonomous agents specifically need: formal affordances for agentic action, constraint declarations for plan validation before execution, and cross-system traversal primitives for multi-hop reasoning across enterprise graphs. Every HydrAI document is a valid Hydra document. Existing clients need no modification.
Every design decision in this implementation (the ontology-driven link ranges, the SHACL shapes graph, the reconciliation tests that make vocab drift a build failure, the IriTemplates for self-describing search, the PUT verification loop that catches silent server failures) reflects a single principle: the API should be smart enough that the agent doesn't have to be.
The enterprise software industry has been shipping integration complexity for decades. AI doesn't change that. Semantics do.
Connect the agent to a Hydra-compliant API and watch it discover capabilities, plan multi-step actions, and execute, with no bespoke integration code of any kind.
← Back to the demo