# APIClarity

> APIClarity is an open source API security and observability tool that captures API traffic in
> a Kubernetes environment, reconstructs OpenAPI specifications from what it observes, and
> flags shadow APIs, zombie APIs, spec drift and authorization problems. It is Apache-2.0
> software you deploy into your own cluster — there is no hosted service, no vendor account and
> no vendor API endpoint. It was part of the OpenClarity project.

> STATUS: END OF LIFE. github.com/openclarity/apiclarity was archived read-only by its owner on
> 2026-05-29 and the wider OpenClarity organisation was archived days later. The last software
> release was v0.14.5 on 2023-05-05. Both project web properties — openclarity.io and
> apiclarity.io — now return HTTP 404 on every path, including their roots. No successor project
> has been announced. The source, the specifications, the Helm charts and the container images
> all remain readable; nothing is being maintained.

> This file was generated by API Evangelist from APIClarity's own published artifacts.
> APIClarity does not publish an llms.txt of its own (probed 2026-09-04: 404 on openclarity.io,
> www.openclarity.io, openclarity.github.io, apiclarity.io, www.apiclarity.io, and no llms.txt
> in the repository).

## What the API is

APIClarity exposes one HTTP API from the deployment you run. Its base is relative — the
published specifications declare `servers: [{url: /api}]` — so the host is whatever Service or
ingress you expose. The documented access path is:

    kubectl port-forward -n apiclarity svc/apiclarity-apiclarity 9999:8080

Module APIs are served under `/api/modules/{module}`.

## Published contracts

- Aggregated global API (OpenAPI 3.0.0, 59 paths, 65 operations): https://raw.githubusercontent.com/openclarity/apiclarity/master/api3/global/openapi.gen.yaml
- Core API (OpenAPI 3.0.0, 23 paths): https://raw.githubusercontent.com/openclarity/apiclarity/master/api3/core/openapi.yaml
- Shared schema library (OpenAPI 3.0.2, 36 schemas): https://raw.githubusercontent.com/openclarity/apiclarity/master/api3/common/openapi.yaml
- Legacy core API (Swagger 2.0): https://raw.githubusercontent.com/openclarity/apiclarity/master/api/swagger.yaml
- Plugins telemetry API (Swagger 2.0) — the contract traffic-source plugins implement: https://raw.githubusercontent.com/openclarity/apiclarity/master/plugins/api/swagger.yaml
- Notification listener API (OpenAPI 3.0.2) — the endpoint YOU implement, that APIClarity POSTs to: https://raw.githubusercontent.com/openclarity/apiclarity/master/api3/notifications/openapi.gen.yaml
- BFLA module (OpenAPI 3.0.3): https://raw.githubusercontent.com/openclarity/apiclarity/master/backend/pkg/modules/internal/bfla/restapi/openapi.yaml
- Fuzzer module (OpenAPI 3.0.3): https://raw.githubusercontent.com/openclarity/apiclarity/master/backend/pkg/modules/internal/fuzzer/restapi/openapi.yaml
- Trace analyzer module (OpenAPI 3.0.3): https://raw.githubusercontent.com/openclarity/apiclarity/master/backend/pkg/modules/internal/traceanalyzer/restapi/openapi.yaml
- Spec differ module (OpenAPI 3.0.3): https://raw.githubusercontent.com/openclarity/apiclarity/master/backend/pkg/modules/internal/spec_differ/restapi/openapi.yaml
- Spec reconstructor module (OpenAPI 3.0.3): https://raw.githubusercontent.com/openclarity/apiclarity/master/backend/pkg/modules/internal/specreconstructor/restapi/openapi.yaml

## Core capabilities

- API inventory — every host/port the deployment has observed traffic to
- OpenAPI reconstruction from live traffic, with a human review/approve step
- Spec diffing — shadow APIs (observed, undocumented), zombie APIs (observed, marked deprecated), and drift
- Trace analyzer — weak authentication, sensitive-data exposure, potential BOLA
- BFLA detector — learns an authorization model from observed traffic, then flags violations
- Fuzzer — actively tests API endpoints against their specification

## Working with it

- Auth: the management API declares no securityScheme in any published contract. The only
  documented credential is `X-Trace-Source-Token`, an optional header a traffic source presents
  to the plugins telemetry API; the token is minted by your deployment when you register a
  trace source with POST /control/traceSources.
- Pagination: `page` and `pageSize` are REQUIRED on GET /apiEvents and GET /apiInventory, with
  `sortKey` and `sortDir`. GET /apiEvents also requires `startTime` and `endTime`.
- Filtering: bracketed operators on the field name — `path[start]`, `statusCode[gte]`,
  `name[contains]`, `hasSpecDiff[is]`, and 40 more.
- Collections return `{ items: [...], total: <n> }`.
- Errors: a bare `{"message": "..."}` object (schema ApiResponse), NOT RFC 9457 problem+json.
  48 of 65 operations declare only a `default` catch-all, so you cannot switch on a code.
- Idempotency: none. No Idempotency-Key header exists anywhere. Retrying a POST acts twice.
- Rate limits: none published and none implemented; there is no vendor quota to exceed.
- Versioning: no version segment, no version header. Three modules expose GET .../version.

## Things an agent should not do unsupervised

- POST /modules/fuzzer/fuzz/{apiID}/start sends real generated traffic at a real API. There is
  no dry-run mode and no idempotency key, and POST .../stop halts the run without unsending
  what has already been delivered.
- DELETE /apiInventory/{apiId}/specs/providedSpec and .../reconstructedSpec have no restore
  path and no stated retention window.
- POST /modules/bfla/authorizationModel/{apiID}/reset discards a learned model irreversibly.
- POST /apiInventory/{reviewId}/approvedReview cannot be un-approved.

## Events

APIClarity POSTs notifications to a listener you implement at POST /notification/{apiID}. Six
types, discriminated on `notificationType`: NewDiscoveredAPINotification, SpecDiffsNotification,
ApiFindingsNotification, AuthorizationModelNotification, TestProgressNotification,
TestReportNotification. No AsyncAPI document is published, and neither retries nor payload
signing is documented.

## Install

- Helm: `helm repo add apiclarity https://openclarity.github.io/apiclarity` then
  `helm install apiclarity apiclarity/apiclarity -n apiclarity --create-namespace`
  (chart v0.14.5, published 2023-05-05; still served, HTTP 200)
- Images: ghcr.io/openclarity/apiclarity (24 tags, newest v0.14.5)
- Go modules: github.com/openclarity/apiclarity, .../plugins/api, .../api3, .../plugins/common
  (the last three are generated client bindings; untagged pseudo-versions from 2024-08-23)

## Traffic sources supported

Istio service mesh (Envoy WASM filter), tap via a DaemonSet, Kong, Tyk, Kuma, and an
OpenTelemetry Collector (traces only). The contract's TraceSourceType enum also names APIGEE_X,
F5_BIG_IP, KONG_INTERNAL and TYK_INTERNAL.

## Try it without a cluster

    DATABASE_DRIVER=LOCAL ENABLE_K8S=false FAKE_TRACES=true \
      FAKE_TRACES_PATH=./backend/pkg/test/trace_files ./backend/bin/backend run

Trace fixtures are committed at backend/pkg/test/trace_files. UI at http://localhost:8080/.

## Links

- Source: https://github.com/openclarity/apiclarity (archived, read-only)
- README: https://github.com/openclarity/apiclarity#readme
- Releases: https://github.com/openclarity/apiclarity/releases
- Issues: https://github.com/openclarity/apiclarity/issues (read-only; 29 open)
- Helm repository: https://openclarity.github.io/apiclarity/index.yaml
- Licence: Apache-2.0 — https://github.com/openclarity/apiclarity/blob/master/LICENSE
- openclarity.io and apiclarity.io: HTTP 404, retired