Skip to main content

Lifecycle, Versions & Audit Log

Every API definition carries a status and moves through a small state machine — the same shape Agent Builder uses for its own workflows, with its own role vocabulary and its own tables for the audit trail and version history.

Statuses​

draft ──(Submit for Review)──► staged ──(Approve & Publish)──► published
  ▲                              │                                 │
  │                              └──(Reject)──► rejected            │
  └──────────────(Move to Draft / Pull Back to Draft)───────────────┘

There are exactly four statuses: draft, staged, published, rejected. There is no cancelled status — an unwanted API definition is deleted instead (only while draft or rejected).

Who can move what, from where​

From statusRoleCan move to
draftapi_developer, lifecycle_manager, space_adminstaged
draftadminstaged, published
stagedlifecycle_manager, space_adminpublished, rejected
stagedadminpublished, rejected, draft
rejectedapi_developer, lifecycle_manager, space_admindraft
rejectedadmindraft, staged
publishedspace_admindraft (pull back for a major revision)
publishedadmindraft, staged

admin here means a global Hrida.ai instance admin — a distinct, wider-reaching role than space_admin, which only has authority within its own API Space. A role not listed for a given from status has no transition available from it at all (for example, api_developer cannot approve or reject a staged definition, and nobody but space_admin/admin can pull a published API back to draft).

Editing (PUT) is only allowed while a definition is draft or rejected — a staged or published definition must be moved back to draft first, exactly like an Agent Builder workflow.

Rejecting requires a reason​

Rejecting a staged API definition requires notes explaining why — the request is rejected with a 400 if notes is omitted.

What happens on publish (and un-publish)​

When a definition transitions to published:

  1. Its version number is bumped (minor version, e.g. 1.0.0 → 1.1.0).
  2. An immutable version snapshot is taken automatically (see below).
  3. It's registered as a Tool Server, immediately callable by Agent Builder agents.

When a published definition is pulled back to draft (or moved to staged by an admin), its Tool Server registration is removed — an unsanctioned API is never left silently callable.

Immutable audit log​

Two separate records are kept, for two different questions:

Lifecycle events — "what state changes has this API been through?"​

Every stage / approve / reject / revise transition writes an immutable ApiLifecycleEvent row: from_status, to_status, actor_id, actor_role, optional notes, and a timestamp. Fetch the full history for a definition:

GET /api/v1/api-definitions/{id}/lifecycle

General audit log — "who changed what field, and when?"​

Separately, every create, field update, publish, unpublish, and delete is recorded in Hrida.ai's general-purpose audit log (resource_type: "API_DEFINITION"), with before/after state snapshots. Fetch it with:

GET /api/v1/api-definitions/{id}/audit-log

Version snapshots & rollback​

An immutable ApiDefinitionVersion snapshot (the OpenAPI spec, name, description, and upstream base URL at that point in time) is created automatically every time a definition is published, and again automatically right before every rollback — so a rollback never destroys the state you're rolling back from. Each snapshot records what triggered it (publish or rollback).

List and inspect snapshots:

GET /api/v1/api-definitions/{id}/versions
GET /api/v1/api-definitions/{id}/versions/{version_id}

Roll back to a prior snapshot:

POST /api/v1/api-definitions/{id}/rollback
{ "version_id": "...", "notes": "optional" }

Rolling back requires the lifecycle_manager, space_admin, or admin role. It restores the OpenAPI spec and upstream base URL from the chosen snapshot, bumps the patch version, and always resets status to draft — a rolled-back API must go through review and be re-published again, it is never silently re-published as-is. If the definition was published at the time, its Tool Server registration is removed as part of the rollback, for the same reason a manual pull-back-to-draft removes it.

Not yet in the builder UI

Version history, inspection, and rollback are available today via the API above. The API Builder edit screen doesn't yet surface a dedicated versions/rollback panel — this is a good candidate for a future UI pass.

Hrida.ai is proprietary software of Zlabs Innovation. See the license for terms. © 2026 Zlabs Innovation.