Docs
audit
The organization's audit log. Each record states who acted, what was done, to which class of governed object, and how it ended.
Amfelt REST API · v1.13.0
· https://api.amfelt.com
GET
/v1/audit-events
List audit events.
Returns one page of the caller’s organization’s audit log, newest first: ordered by occurred_at and then id, both descending. Filters combine with AND; since is inclusive and until is exclusive. Page with the opaque cursor — pass back next_cursor to read the next page. A cursor marks a position in that ordering, so events recorded while a client is paging do not shift the pages that follow. The actor is returned as recorded: a kind and a bare identifier.Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Tenant-Slug | header | Yes | string | Slug of the organization to scope the request to; required for user-authenticated requests. |
Slug of the organization to scope the request to; required for user-authenticated requests. | ||||
since | query | No | string | Only events at or after this instant (inclusive). |
Only events at or after this instant (inclusive). | ||||
until | query | No | string | Only events before this instant (exclusive). |
Only events before this instant (exclusive). | ||||
actor_kind | query | No | AuditActorKind | Only events by this kind of actor. |
Only events by this kind of actor. | ||||
actor_id | query | No | string | Only events by the account or agent with this identifier. |
Only events by the account or agent with this identifier. | ||||
action | query | No | AuditAction | Only events of this action. |
Only events of this action. | ||||
object_type | query | No | AuditObjectType | Only events that addressed this class of governed object. |
Only events that addressed this class of governed object. | ||||
object_id | query | No | string | Only events that addressed the object with this identifier. |
Only events that addressed the object with this identifier. | ||||
outcome | query | No | AuditOutcome | Only events with this outcome. |
Only events with this outcome. | ||||
cursor | query | No | string | Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response. |
Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response. | ||||
limit | query | No | integer | Maximum number of items to return per page. |
Maximum number of items to return per page. | ||||
Responses
200
A page of audit events.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
data | AuditEvent [] | Yes | The page of events, newest first. |
The page of events, newest first. | |||
next_cursor | [string null] | No | Opaque cursor for the next page, or null when this is the final page. |
Opaque cursor for the next page, or null when this is the final page. | |||
400
The request was malformed or failed validation.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
401
The request lacks valid credentials.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
403
The caller is authenticated but not permitted to perform the request.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
Security
bearer_jwt
Schemas
Audit Event List
type: AuditEventList
A page of audit events.
| Property | Type | Required | Description |
|---|---|---|---|
data | AuditEvent [] | Yes | The page of events, newest first. |
The page of events, newest first. | |||
next_cursor | [string null] | No | Opaque cursor for the next page, or null when this is the final page. |
Opaque cursor for the next page, or null when this is the final page. | |||
Audit Event
type: AuditEvent
One audit record.
| Property | Type | Required | Description |
|---|---|---|---|
action | AuditAction | Yes | |
actor_id | [string null] | No | Identifier of the acting account or agent, as recorded; null when actor_kind is system or anonymous. |
Identifier of the acting account or agent, as recorded; null when actor_kind is system or anonymous. | |||
actor_kind | AuditActorKind | Yes | |
detail | AuditEventDetail | No | |
id | string | Yes | Identifier of the audit record. |
Identifier of the audit record. | |||
oauth_client_id | [string null] | No | The delegated OAuth client the act arrived through; null for direct user and agent traffic. |
The delegated OAuth client the act arrived through; null for direct user and agent traffic. | |||
object_id | [string null] | No | Identifier of the object acted on; null for a query and for an act refused before the object was resolved. |
Identifier of the object acted on; null for a query and for an act refused before the object was resolved. | |||
object_type | AuditObjectType | Yes | |
occurred_at | string | Yes | When the act happened. |
When the act happened. | |||
outcome | AuditOutcome | Yes | |
Audit Action
type: AuditAction
What was done: read (one object), query (one collection read, recorded once for the whole result), create, update, or delete.
Audit Actor Kind
type: AuditActorKind
Who acted: account (a signed-in member), agent (an agent-authenticated call), system (a scheduled job or webhook receipt), or anonymous (the request was refused before an identity was established).
Audit Event Detail
type: AuditEventDetail
Optional structured detail recorded with an event. environment_id names the DTAP environment a policy act addressed (object type agent_version_policy).
| Property | Type | Required | Description |
|---|---|---|---|
environment_id | EnvironmentSlug | No | |
filter | string | No | The filter a query event applied. |
The filter a query event applied. | |||
from_version | string | No | The agent version before an agent version act (upgrade, promote, rollback): the agent’s running version, or the policy’s previous pin. Examples: 5.1.3. |
The agent version before an agent version act (upgrade, promote, rollback): the agent’s running version, or the policy’s previous pin. Examples: 5.1.3. | |||
operation | string | No | Which operator action an event records: pause or resume on a schedule update event (object type schedule), rerun on a run create event (object type run), upgrade or rollback on an agent event (object type agent), promote or rollback on a policy change (object type agent_version_policy), and approve or decline on a decision (object type approval_request). An agent event’s rollback moves the agent down to a target a rollback lowered, dispatched by the orchestrator or retried by hand. A policy change that is neither a promotion nor a rollback, such as a mode switch or a new settle delay, is an update event on agent_version_policy with no operation. The closed set is complete; the pause reason the operator gave is not recorded in the audit detail. Valid values are: pause, resume, rerun, upgrade, promote, rollback, approve, decline. |
Which operator action an event records: pause or resume on a schedule update event (object type schedule), rerun on a run create event (object type run), upgrade or rollback on an agent event (object type agent), promote or rollback on a policy change (object type agent_version_policy), and approve or decline on a decision (object type approval_request). An agent event’s rollback moves the agent down to a target a rollback lowered, dispatched by the orchestrator or retried by hand. A policy change that is neither a promotion nor a rollback, such as a mode switch or a new settle delay, is an update event on agent_version_policy with no operation. The closed set is complete; the pause reason the operator gave is not recorded in the audit detail. Valid values are: pause, resume, rerun, upgrade, promote, rollback, approve, decline. | |||
reason | string | No | A token from the api’s closed reason set: a denial reason on a denied event, for example invalid_token or missing_permission:<permission>, or an automation marker on an allowed event, for example onboarding_automatic for a change onboarding made by itself. It is never free text, so it never carries an operator’s pause reason. A token longer than 64 characters is cut at 64. |
A token from the api’s closed reason set: a denial reason on a denied event, for example invalid_token or missing_permission:<permission>, or an automation marker on an allowed event, for example onboarding_automatic for a change onboarding made by itself. It is never free text, so it never carries an operator’s pause reason. A token longer than 64 characters is cut at 64. | |||
result_count | integer | No | How many results a query event returned. |
How many results a query event returned. | |||
to_version | string | No | The agent version after an agent version act (upgrade, promote, rollback): the upgrade’s target, or the policy’s new pin. Examples: 5.2.0. |
The agent version after an agent version act (upgrade, promote, rollback): the upgrade’s target, or the policy’s new pin. Examples: 5.2.0. | |||
Environment Slug
type: EnvironmentSlug
The slug of a DTAP environment.
Audit Object Type
type: AuditObjectType
The class of governed object the act addressed.
Audit Outcome
type: AuditOutcome
How the act ended: allowed, denied (the policy refused it), or error (it was permitted but failed).
Error
type: Error
The standard error envelope returned by every non-2xx response.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. |
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument. | |||
field | string | No | Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. |
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug. | |||
message | string | Yes | Human-readable description of the error. Examples: limit must be between 1 and 100. |
Human-readable description of the error. Examples: limit must be between 1 and 100. | |||
Last updated on October 31, 2026