REST API and tokens

The ArchNGN REST API gives machine callers — CI/CD pipelines, AI coding agents, internal tooling — read access to your architecture and the ability to check a change against it before it ships.

Base path is /api/v1 on your plane’s host. The console shows the host to use beside each API token.

Authentication

Every call carries a bearer token:

curl -H "Authorization: Bearer angn_prod_..." \
  https://app.archngn.com/api/v1/meta

Each token is bound to your account, carries a fixed set of scopes, and can be limited to specific workspaces.

Create a token

Open Integrations → API Tokens and click Add New Token, or choose API Token from + New. Creating and revoking tokens is for account admins.

Field	What to enter
Name	Name it after what uses it, such as payments-api CI pipeline. That is what you will read when deciding whether it is safe to revoke.
Expires	30 days, 90 days, 1 year, or 2 years at most.
Permissions	The scopes below. A token has no role and inherits nothing: its scopes are its entire authority.
Limit to specific workspaces	Tick to bind the token to chosen workspaces. Unticked, it can read every workspace in the account.

The token is shown once, when you create it. Copy it into your pipeline’s or agent’s secret store straight away. The API Tokens tab lists each token’s permissions, workspaces, status, expiry and when it was last used, and revokes it.

Start with /meta. It reports the token’s scopes, workspace binding, expiry, rate limits and what each check mode costs, so an integration never has to discover its limits by hitting them.

Scopes

Scope	Opens
arch:read	Standards, components, the metamodel, context search, and the whole MCP tool surface
check:run	Running design checks and reading their history
check:waive	Accepting and revoking risks on check findings (waivers in the API)
audit:read	The account’s audit trail

check:waive is deliberately separate from check:run. A pipeline token that could both run checks and silence the ones it fails is not a gate. See Token scopes and safety below.

Endpoints

Method	Path	Purpose
GET	/meta	What this token can do, and its limits
GET	/workspaces	Workspaces this token can see, with counts
GET	/metamodel	Element and relationship types your account permits
GET	/workspaces/{id}/standards	Governing standards, with their reasoning
GET	/standards/{id}	One standard, full normative text
GET	/workspaces/{id}/components	Current-state registry objects
GET	/components/{id}	One component, its integrations and the standards governing it
POST	/workspaces/{id}/context:search	A retrieval context pack for a query
POST	/checks	Grade a change against the architecture
GET	/checks/{id}	One check: a queued review, or a recorded result
GET	/workspaces/{id}/checks	Recorded check history
GET/POST	/workspaces/{id}/waivers	List or create waivers
GET/DELETE	/waivers/{id}	Read or revoke one waiver

The reasoning travels with the rule

Wherever a standard appears — a list, a single fetch, a context pack, or the evidence on a check finding — it carries the why alongside the rule:

{
  "name": "Integration Standard 4.2",
  "lifecycle_status": "Invest",
  "approved": true,
  "intent": "Keep money movements reconcilable within one transaction boundary.",
  "rationale": "Payments reconciliation is audited end-to-end; a synchronous call keeps the ledger write inside the caller's transaction.",
  "consequences": "Event-driven writes need a compensating reconciliation process and an agreed eventual-consistency window with Finance.",
  "owner": "Payments Architecture",
  "has_business_context": true
}

This is the difference that matters in practice. A caller told “violates Integration Standard 4.2” has learned a rule to route around. One told why can comply, propose an alternative that preserves the intent, or raise a conscious decision with the trade-off already articulated.

A field nobody has captured comes back as null, never "", so you can tell “not written down” from “the author had nothing to say”. has_business_context: false flags a standard that can be quoted but not explained — usually worth chasing its owner about.

Conventions

Errors are RFC 9457 application/problem+json, one shape everywhere. Branch on type, never on message text, and quote request_id in a support report.

Pagination uses opaque keyset cursors, never offsets: the registry changes under a long scan, so an offset page would silently skip records. Pass next_cursor back verbatim.

A resource belonging to another account returns 404, not 403. A 403 would confirm the id exists, which turns any endpoint taking an id into an existence oracle.

Every relationship carries evidence: observed, stated or inferred — whether the platform read the link, a person stated it, or the platform guessed it. Weigh an inferred link accordingly. See Link evidence.

Versioning: /api/v1 is additive-only. New fields and endpoints may appear; existing ones will not change meaning. A breaking change means /api/v2. Treat unknown fields as forward compatibility rather than errors.

Rate limits and allowance

Two different controls:

• Rate limits are per token, per process: 60 reads a minute, 20 checks a minute. They bound runaway loops, not contractual quotas. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
• Your monthly credit allowance bounds billable work. It is checked before every deep check and every review. Reads are never metered — charging for architecture context would discourage exactly the behaviour the product exists to encourage.

Token safety

One token per consumer, not one per account. A CI token and an agent token that share a credential also share a revocation.

Bind it to a workspace when the consumer only touches one. A bound token cannot see anything outside its binding, over REST or over MCP.

Set an expiry. Rotation is mint-then-revoke, so two tokens can be live at once and you swap with no downtime.

Only a hash of each token is stored. The plaintext is shown once, at creation, and there is no recovery path — mint a new one. If a token leaks, revoke it in Integrations → API Tokens (immediate, no cache to wait out), mint a replacement, and read the audit trail: every action carries the token id that performed it.

Webhooks

Not available yet. Outbound event notifications are a separate capability and are not part of the API today; poll the endpoints above, or run checks from your pipeline where the event you care about already happens.

Related

• Design Checks: gate a pipeline on the architecture, with SARIF, JUnit and markdown output.
• MCP Server: the same architecture, shaped for AI coding agents.
• Members and Roles: capabilities and custom roles.
• Usage: what each check mode costs.