HTTP API

Hikyo exposes an OpenAPI 3.1 contract under /api/v1. The repository’s api/openapi.yaml is the source of truth for routes, schemas, security, and operation semantics.

Start with discoveryCopy Anchor Link

curl --fail https://hikyo.example.com/api/v1/meta

The unauthenticated response reports the server version, API revision, instance identity, and protocol capabilities, including available authentication flows and delivery-status report support. It contains no tenant configuration.

Authentication channelsCopy Anchor Link

CLI clients present the stored session artifact as Authorization: Bearer. Browser sessions use secure HttpOnly cookies and a companion CSRF mechanism for state-changing requests.

Do not copy browser cookies into automation. Use a service account credential or an OIDC federation binding.

Contract rulesCopy Anchor Link

• Requests are validated before a handler runs.
• Responses use one uniform error model.
• Unauthorized and missing tenant resources have the same status and shape.
• Responses may gain fields within /api/v1; clients must ignore unknown fields.
• Open enums may gain values; closed enums do not.

The contract records operation-specific authorization, accepted artifact types, and the minimum API revision. Generate clients from the checked-in document, then preserve unknown response fields and enum values.

API errorsCopy Anchor Link

Treat the HTTP status and stable error code as machine-readable. Human detail is safe only where the contract permits it and must not be parsed as an API.

Do not retry authentication or policy refusals. Retry unavailable responses only with bounded backoff and after respecting operation idempotency.

Health is outside the APICopy Anchor Link

GET /healthz and GET /readyz are unauthenticated probes on the separate operational listener (127.0.0.1:8081 by default, configured with HIKYO_OPERATIONAL_LISTEN or --operational-listen). They are not served by the application listener on port 8080 and do not accept session credentials. Keep the operational listener private.

CompatibilityCopy Anchor Link

Hikyo is still 0.x; interfaces are not frozen. Match generated clients to the server revision and check /api/v1/meta before using a newer operation.

For interactive work, prefer the CLI. It implements trust establishment, target echoing, safe secret input, and display-once output.