openapi-sync

A project rule for keeping an OpenAPI description accurate when an API or command-line interface changes. OpenAPI is a machine-readable document describing HTTP routes, inputs, outputs, and errors.

In plain words
What is it for?
Updating API paths, request and response schemas, status codes, query parameters, and CLI commands, then checking the specification with a linter.
Why use it?
It prevents the documented API from drifting away from what the server and command-line tool actually support.

Cursor rule for Cursor

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add rules/orlojhq/orloj/openapi-sync
Clone the repo
git clone --depth 1 https://github.com/OrlojHQ/orloj

Made for: Cursor.

Per session 0 Nothing until a file matches its globs; then the whole rule loads.
When invoked 398 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00000 $0.00398
Opus 5 $0.00000 $0.00199
Sonnet 5 $0.00000 $0.00080
Haiku 4.5 $0.00000 $0.00040

Measured 2d ago against content hash 58ba91285909, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

openapi-sync scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.cursor/rules/openapi-sync.mdc · 28 lines

What it actually says

OpenAPI and API surface

Shared agent guidance lives in .agents/rules.md. Keep this Cursor rule consistent with that file.

When you change any of the following, update openapi/ so paths and schemas stay accurate, then run the same check as CI:

npx --yes @redocly/[email protected] lint openapi/openapi.yaml

Usually requires OpenAPI updates

  • api/ — new or changed routes, status codes, query params, or JSON bodies on the control-plane API.
  • Resource JSON shipped over the API — Go types in resources/ (and related handlers) when they change serialized shape fields users or orlojctl apply send/receive.
  • orlojctl — new subcommands or flags that call new or changed HTTP endpoints or bodies (extend the spec to match what the server actually does).

Often does not require OpenAPI updates

  • Offline-only CLI (e.g. manifest parse/validate with no new HTTP contract).
  • Internal refactors with identical wire format.
  • Docs-only changes outside the spec.

When unsure, compare api/server.go route registration and handler payloads to openapi/openapi.yaml (and split schemas under openapi/schemas/). OpenAPI lint can pass even when a newly added Go resource field is missing from openapi/schemas/, so check resource schema changes manually. Regenerate the bundled root doc when your workflow uses openapi/build_openapi.py.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 28 lines · 0 tokens per session scan A 58ba91285909

Subscribe to this mod's changes

openapi-sync is a cursor rule published in the GitHub repository OrlojHQ/orloj (117 stars, last pushed 5d ago), licensed Apache-2.0. It costs nothing until one of its globs matches a file; then it loads 398 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.