---
title: 5ac.vn G-Company OS — API Catalog & Developer Docs
description: RFC 9727-style API catalog for 5ac.vn (G-Company OS). Machine-readable endpoint inventory — method, auth, description — for agents and integrators. Complements the OpenAPI 3.1 spec.
type: api-catalog
version: 1.20.0
url: https://5ac.vn/api-catalog.md
---

# G-Company OS — API Catalog

This catalog inventories the machine-readable API surface published by 5ac.vn
(G-Company OS). It follows the spirit of **RFC 9727 (api-catalog)** — a standardized
way for agents and tools to discover every API a publisher exposes — expressed as a
readable Markdown index. The authoritative machine contract is
[`/openapi.json`](https://5ac.vn/openapi.json) (OpenAPI 3.1).

## Base URL

All public discovery endpoints are served at the root:

```
https://5ac.vn
```

Protected runtime endpoints are versioned under the Hermes gateway of each
self-hosted deployment (see `/auth.md`).

## Discovery & documentation endpoints

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/openapi.json` | `GET` | none | OpenAPI 3.1 spec — full API contract, versioning, rate limits, RFC 9457 errors |
| `/llms.txt` | `GET` | none | LLM-readable site index (the AI equivalent of robots.txt) |
| `/pricing.md` | `GET` | none | Machine-readable pricing tiers |
| `/AGENTS.md` | `GET` | none | Operating guide for coding agents working on the site |
| `/agent-docs.md` | `GET` | none | Agent guide — what G-Company OS does, when to use it, endpoints, auth |
| `/auth.md` | `GET` | none | Agent authentication guide — auth methods, flows, request examples |
| `/api-catalog.md` | `GET` | none | This file — the RFC 9727 endpoint inventory |
| `/docs/index.md` | `GET` | none | Developer portal (markdown) |
| `/.well-known/mcp.json` | `GET` | none | MCP server manifest (Model Context Protocol discovery) |
| `/.well-known/agent-card.json` | `GET` | none | A2A agent card (capabilities, skills) |
| `/.well-known/agent-discovery` | `GET` | none | Flat agent discovery index (entry points) |
| `/nlweb/schema-feed.json` | `GET` | none | NLWeb schema feed (natural-language web protocol) |
| `/sitemap.xml` | `GET` | none | Full sitemap |
| `/robots.txt` | `GET` | none | Crawler rules |

## Runtime endpoints (self-hosted)

The G-Company OS **agent runtime** (Hermes Agent) is not a public REST CRUD API. It
is invoked through the **Hermes gateway** per deployment, authenticated with a
per-deployment bearer token. Standard gateway surface (see Hermes Agent docs):

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/agent/run` | `POST` | bearer token | Dispatch a task to a named agent profile |
| `/agent/status` | `GET` | bearer token | Check an agent run's status |
| `/agent/ask` | `POST` | bearer token | Ask a question to the agent platform (NLWeb) |
| `/brain/query` | `POST` | bearer token | Query the Gbrain RAG knowledge base (PostgreSQL + pgvector) |
| `/gateway/message` | `POST` | bearer token | Ingest a message into the multi-channel gateway (Telegram / Discord / Zalo / Email / CLI) |

> These runtime endpoints run inside a customer's own G-Company OS deployment; they
> are **not** hosted on the public 5ac.vn domain. Token issuance is an operator
> responsibility (see `/auth.md`, Method B).

## Agent-registration endpoints (auth.md protocol)

For services built on G-Company OS that implement agentic registration, the
standard `auth.md` surface applies (RFC 7523 / RFC 7009 / RFC 8414 + WorkOS
`auth.md` extension):

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/.well-known/oauth-protected-resource` | `GET` | none | Protected Resource Metadata (scopes, bearer methods, AS list) |
| `/.well-known/oauth-authorization-server` | `GET` | none | Authorization Server metadata + `agent_auth` block |
| `/agent/identity` | `POST` | none / ID-JAG | Register an agent identity (`identity_assertion`, `service_auth`, or `anonymous`) |
| `/agent/identity/claim` | `POST` | claim token | Start/refresh the user claim ceremony (returns `user_code` + `verification_uri`) |
| `/oauth2/token` | `POST` | assertion | Exchange identity assertion for an access token (RFC 7523 JWT-bearer grant) |
| `/oauth2/revoke` | `POST` | token | Revoke an access token (RFC 7009) |

## Response conventions

- **Errors:** every 4xx/5xx returns **RFC 9457 Problem Details**
  (`application/problem+json`) with the typed `Error` body.
- **Rate limiting:** responses carry `RateLimit-Limit` / `RateLimit-Remaining` /
  `RateLimit-Reset` headers; `429` adds `Retry-After`.
- **Versioning:** public paths are unversioned and stable; breaking changes to the
  runtime API ship only under a new major version with a 6-month overlap (see
  `openapi.json`).

## Related

- [OpenAPI 3.1 spec](https://5ac.vn/openapi.json) — authoritative machine contract
- [Agent guide](https://5ac.vn/agent-docs.md) — what G-Company OS does and when to use it
- [Authentication](https://5ac.vn/auth.md) — how to authenticate to the API