API specs are some of the most valuable artifacts in a codebase, yet they almost never appear in architecture documentation. We're changing that. Archyl now lets you import OpenAPI, gRPC, GraphQL, and AsyncAPI contracts and link them directly to your C4 model.

API Contracts: Your API Specifications, Linked to Your Architecture

A few weeks ago, I was reviewing a system architecture with a team that had a beautiful C4 diagram. Containers were well-defined. Relationships had clear labels. Everything looked great—until someone asked "what does the API between the Order Service and the Payment Gateway actually look like?"

Silence. The diagram said "REST/JSON." The OpenAPI spec lived in a different repository. The actual endpoint list was in a Notion page that hadn't been updated since the last intern left. Three sources of truth for one API surface, and none of them agreed.

This is absurdly common. API specifications are some of the most precise, machine-readable artifacts in a codebase. Yet in architecture documentation, they're invisible. You get a box, an arrow, and a protocol label. The actual contract—the endpoints, the schemas, the fields—lives somewhere else entirely.

We built API Contracts to fix this. Your API specs now live inside your architecture, linked to the elements that implement and consume them.

Four Protocols, One Home

Modern systems rarely speak a single protocol. Your public API is REST, your internal services communicate over gRPC, and your frontend fetches data through GraphQL. Each has its own spec format, its own tooling, its own documentation ecosystem.

Archyl's API Contracts support all four:

OpenAPI / Swagger — Import your OpenAPI 3.x or Swagger 2.0 specs and get an interactive reference viewer powered by Scalar. Endpoints are grouped, parameters are documented, schemas are expandable. It's the same experience you'd get from a dedicated API documentation tool, embedded directly in your architecture workspace.

gRPC / Protocol Buffers — Paste or sync your .proto definitions. The viewer renders services, methods, message types, and enums with syntax highlighting and proper indentation. No more hunting through proto files to understand what a service exposes.

GraphQL — Import your schema and explore types, queries, mutations, and subscriptions. And if you've configured server endpoints, you get a full GraphiQL playground—write queries, execute them against your actual API, and explore the schema interactively, all without leaving Archyl.

AsyncAPI — Define your event-driven APIs with AsyncAPI specifications. The viewer renders channels, operations, message schemas, and server bindings with full syntax highlighting. Whether you're using Kafka, RabbitMQ, NATS, or WebSockets, AsyncAPI contracts document what events your services produce and consume.

Import From Git or Paste Directly

API specs change. An endpoint gets added, a field gets deprecated, a new version ships. If your documentation requires manual copy-paste to stay current, it won't stay current.

That's why API Contracts support two source modes:

Git Sync connects your contract to a spec file in a repository. Point it to your openapi.yaml, your service.proto, your schema.graphql, or your asyncapi.yaml, and Archyl fetches the content directly. When the spec changes upstream, hit sync and the contract updates. This works with every git provider Archyl supports—GitHub, GitLab, Bitbucket, Azure DevOps, and self-hosted instances.

Manual is for teams that don't keep specs in git, or for quick prototyping. Paste your spec content directly and edit it in place. Useful for drafting a contract before the service exists, or for importing a spec from a third-party API you don't control.

Both modes support versioning, so you can track which version of the contract you're documenting.

Linked to Your Architecture

Here's where API Contracts become more than a spec viewer.

Every contract can be linked to one or more C4 elements—systems, containers, components, or code elements. An OpenAPI spec can be linked to the API Gateway container that serves it. A gRPC proto can be linked to the microservice component that implements it. A GraphQL schema can be linked to the BFF (Backend for Frontend) that exposes it.

These links are bidirectional. From the contract, you see which architecture elements it relates to. From the element's detail panel on the diagram, you see which contracts describe its API surface. When you right-click a container on the canvas, you can link and unlink contracts directly from the context menu.

This closes the gap I described at the beginning. When someone asks "what does the API between these two services look like?", the answer is one click away. Not in a different tool, not in a different repo—right there on the diagram.

Event Channels

Event-driven architectures are notoriously hard to document. Which service publishes to which topic? What's the message schema? Who consumes it?

Archyl's Event Channels bring visibility to your asynchronous communication. Each AsyncAPI contract automatically surfaces the channels it defines — topics, queues, streams — and maps them to the C4 elements that produce and consume events.

On the diagram, event channels appear as distinct connection types, making it immediately clear which relationships are synchronous API calls and which are asynchronous event flows. This is critical for understanding system behavior: a REST call between two services has very different reliability and coupling characteristics than an event published to a message broker.

You can also create event channels independently of AsyncAPI contracts, useful for documenting legacy messaging systems or proprietary protocols that don't have a formal spec.

Interactive Viewers

We didn't want contracts to be raw text blobs. Each protocol gets a purpose-built viewer:

The OpenAPI viewer renders a fully interactive API reference. Endpoints are organized by tag, with expandable request/response schemas, parameter documentation, and authentication details. If you've defined server URLs, the viewer shows them so developers know where to send requests. It's a real API documentation experience, not a syntax-highlighted YAML dump.

The Protocol Buffer viewer renders proto definitions with proper syntax coloring, making services, RPCs, and message structures easy to scan.

The GraphQL viewer highlights types, fields, and directives. And when you've configured a server endpoint, a second tab opens a full GraphiQL playground. You can write and execute queries against your live API, explore the schema through introspection, and test mutations—all embedded in Archyl. If your GraphQL API has multiple environments (staging, production), you can define multiple server entries and switch between them.

The AsyncAPI viewer renders your event-driven API definitions with channel listings, message schemas, and server/broker configurations. Each channel shows its operations (publish/subscribe), payload schemas, and bindings — giving developers a clear picture of your event-driven communication surface.

How to Get Started

Navigate to any project and open the API Contracts section from the sidebar. Click "Add Contract" and choose your protocol type and source mode.

For git-sourced contracts, connect a repository (or reuse one already connected to your project), specify the file path and branch, and Archyl fetches the spec. For manual contracts, paste the content directly.

Once created, head to the diagram and link the contract to the relevant C4 elements. From that point on, anyone exploring the architecture can drill into the actual API surface from the diagram itself.

Why This Matters

Architecture diagrams are powerful for showing structure—what exists and how things connect. But they've always been weak on interfaces. A relationship arrow labeled "REST/HTTPS" tells you almost nothing about what actually flows between two services. An event published to a Kafka topic is even more opaque — unless you have the AsyncAPI spec and channel mapping right there.

API contracts fill that gap. They add precision to the arrows. When a new team member looks at your architecture and sees a connection between the Mobile App and the API Gateway, they can immediately open the OpenAPI spec and understand exactly what endpoints are available, what data structures are exchanged, and what authentication is required.

This is architecture documentation that earns its keep. Not because someone mandated it, but because it answers real questions that come up every day.

Already using Archyl for your architecture? Explore the API Contracts feature in your project. New to the platform? Learn about the C4 model and how AI-powered discovery can generate your architecture diagram automatically.

API Contracts: Your API Specifications, Linked to Your Architecture - Archyl Blog