Audit API
Read the append-only audit log for your organization — who did what, when — with cursor or page pagination and filters.
The Audit API is a read-only feed of the append-only audit log for your active organization: an event per
significant action (logins, member changes, deployments, settings edits, and more), newest first. In the
dashboard this is the Audit page; there's no dedicated CLI command — reach it through
openship api.
Base path & auth
All paths are relative to your instance, under /api — e.g. https://your-host/api/audit.
Send a personal access token as a bearer header (Authorization: Bearer <token>), created with
openship token create. The dashboard uses your session cookie instead. See the
API overview for the full auth model.
Endpoints
| Method & path | Permission | What it does |
|---|---|---|
GET /api/audit | audit:read | List audit events for the active org (newest first), with cursor or page pagination and filters. |
List audit events
GET /api/auditEvery event is scoped to your active organization. Access is gated by role: owners and admins always see the
log, plain members are denied, and restricted users need an explicit audit:read grant on the org-level
audit resource. See permissions & roles.
Query parameters
All parameters are optional. Choose one pagination mode: pass cursor (keyset) or page/perPage
(offset). Cursor mode is recommended for anything that streams pages — it survives concurrent writes without
shifting rows; page mode powers the dashboard's "Showing 1–50 of N" count.
Prop
Type
Response
Each event row carries id, eventType, resourceType, resourceId, before/after JSON snapshots
(mutation events only; otherwise null), ipAddress, userAgent, and createdAt. Rows are enriched with an
actor object ({ id, email, name }) resolved from actorUserId, or null for system-emitted events.
The pagination envelope depends on the mode:
- Cursor mode →
{ data, pageInfo: { hasNextPage, endCursor } }. PassendCursorback ascursorfor the next page; there is nototal. - Offset mode →
{ data, total, page, perPage }.
# Cursor mode — newest 50 deployment-failure events
curl -G https://your-host/api/audit \
-H "Authorization: Bearer $OPENSHIP_TOKEN" \
--data-urlencode "cursor=" \
--data-urlencode "limit=50" \
--data-urlencode "eventType=deployment.failed"# Same thing via the CLI escape hatch (path is relative to /api):
openship api /audit -q eventType=deployment.failed -q limit=50Errors you might see
403 — not permitted
Your role can't read the audit log. Members are denied by default; ask an owner/admin to grant audit:read
on the org's audit resource, or view the log from an admin account. See
permissions & roles.
Empty results, not an error
Filters that match nothing return 200 with an empty data array. Double-check eventType spelling
(it's the exact dot-namespaced tag) and that resourceId belongs to your organization. Retention is
org-configurable (default 90 days), so events older than the window are pruned and won't appear.