Events

Authentication: JWT | API Key

Events provide an immutable audit log of all changes in your FoxNose organization. Each create, update, or delete operation on entities automatically generates an event record. Events are read-only and cannot be modified or deleted via the API.

There are two types of events:

  • Environment Events — Track changes to environment-scoped entities (folders, resources, components, APIs, etc.)
  • Global Events — Track changes to organization-level entities (users, projects, and environment lifecycle events)

For non-admin users, environment events are filtered on the backend to include only entities they can read based on permissions (including object-level folder access).

Path Parameters

  • Name
    :env
    Type
    string
    Description

    Unique identifier of the environment (only for environment events)

Event Object

  • Name
    key
    Type
    string
    Description

    Unique identifier for the event.

  • Name
    timestamp
    Type
    datetime
    Description

    When the event occurred, in ISO 8601 format.

  • Name
    event_type
    Type
    string
    Description

    Type of change: "create", "update", or "delete".

  • Name
    entity_type
    Type
    string
    Description

    Type of entity that was changed. For environment events: folder, resource, revision, component, version, api, manageapikey, fluxapikey, managepermissionrole, fluxpermissionrole, envrole, fluxrole, locale. For global events: user, customer, project, environment.

  • Name
    entity_key
    Type
    string
    Description

    Unique identifier of the entity that was changed.

  • Name
    actor_type
    Type
    string
    Description

    Type of actor who made the change: "user" or "apikey" (global events only support "user").

  • Name
    actor
    Type
    object | null
    Description

    Details about the actor. For users: key, email, first_name, last_name, full_name, deleted_at. For API keys: key, description, public_key, role, created_at, environment, deleted_at. Returns null if actor information is unavailable.

  • Name
    ip_address
    Type
    string | null
    Description

    IP address from which the change was made, or null if unavailable.

  • Name
    referer
    Type
    string | null
    Description

    Request host extracted from the HTTP Referer header (e.g., app.foxnose.net). Only the host portion is stored for privacy and easier filtering. Returns null if unavailable.

  • Name
    metadata
    Type
    object | null
    Description

    Additional metadata associated with the event. Structure depends on entity type and action. See Metadata by Entity Type for details.

Metadata by Entity Type

The metadata field contains additional context about the event. Its structure varies depending on the entity type and action performed.

EventConditionMetadata Fields
Folder Events
folder:create
folder:update
folder:delete		Folder created, updated, or deletedparent_key: key of parent folder (or null for root)
previous_parent_key (update only): key of old parent folder
snapshot (delete only): last known folder fields (see Delete Snapshots)
Component Events
component:create
component:delete		Component created or deletedsnapshot (delete only): last known component fields (see Delete Snapshots)
Version Events
version:create
version:delete		Version created or deletedschema_key: key of the schema (components only, null for collections)
schema_type: "component" or "collection"
folder_key: key of the folder (collections only, null for components)
snapshot (delete only): last known version fields (see Delete Snapshots)
version:updateVersion publishedaction: "publish"
schema_key: key of the schema (components only, null for collections)
schema_type: "component" or "collection"
folder_key: key of the folder (collections only, null for components)
Locale Events
locale:create
locale:update
locale:delete		Locale created, updated, or deletedcode: locale code
name: locale name
is_default: whether locale is default
snapshot (delete only): last known locale fields (see Delete Snapshots)
Environment Events (Global)
environment:create
environment:update
environment:delete		Environment created, updated, or deletedproject_key: key of the parent project
snapshot (delete only): last known environment fields (see Delete Snapshots)
Resource Events
resource:create
resource:update
resource:delete		Resource created, updated, or deletedfolder_key: key of the resource's folder
snapshot (delete only): last known resource fields (see Delete Snapshots)
Revision Events
revision:create
revision:delete		Revision created or deletedfolder_key: key of the resource's folder
resource_key: key of the resource
snapshot (delete only): last known revision fields (see Delete Snapshots)
Flux API Events
api:updateFolder connected to Flux APIaction: "connect"
folder_key: key of the connected folder
allowed_methods: array of permissions (e.g., ["get_one", "get_many"])
api:updateFolder permissions updatedaction: "update_permissions"
folder_key: key of the folder
allowed_methods: updated array of permissions
api:updateFolder disconnected from Flux APIaction: "disconnect"
folder_key: key of the disconnected folder
API Key Events
manageapikey:create
manageapikey:update
manageapikey:delete		Management API key created, updated, or deletedrole_key: key of assigned role (or null)
snapshot (delete only): last known key fields (see Delete Snapshots)
fluxapikey:create
fluxapikey:update
fluxapikey:delete		Flux API key created, updated, or deletedrole_key: key of assigned role (or null)
snapshot (delete only): last known key fields (see Delete Snapshots)
Role Events
envrole:create
envrole:update
envrole:delete		Management role created, updated, or deletedname: role name
description: role description
full_access: whether role has full access
snapshot (delete only): last known role fields (see Delete Snapshots)
fluxrole:create
fluxrole:update
fluxrole:delete		Flux role created, updated, or deletedname: role name
description: role description
full_access: always null for Flux roles
snapshot (delete only): last known role fields (see Delete Snapshots)
Permission Role Events
managepermissionrole:create
managepermissionrole:update
managepermissionrole:delete		Management role permission created, updated, or deletedrole_key: key of the role
content_type: permission type
actions: allowed actions list
all_objects: whether applies to all objects
snapshot (delete only): last known permission fields (see Delete Snapshots)
fluxpermissionrole:create
fluxpermissionrole:update
fluxpermissionrole:delete		Flux role permission created, updated, or deletedrole_key: key of the role
content_type: permission type
actions: allowed actions list
all_objects: whether applies to all objects
snapshot (delete only): last known permission fields (see Delete Snapshots)
Global Entity Events
project:delete
customer:delete		Project or organization deletedsnapshot: last known fields (see Delete Snapshots)

Delete Snapshots

When an entity is deleted, events include a metadata.snapshot object with the last known public fields for that entity. The snapshot is intentionally minimal and excludes large payloads.

EntitySnapshot Fields
environmentname, host, project_key, project_id, customer_key, block_reason, block_last_state_enabled, protected_by_user_uid
projectname, gdpr, customer_key, region_key, region_code, region_name
customername, legal_name, tax_num, city, province, country_iso, zip_code, block_reason, owner_uid
foldername, folder_type, content_type, alias, path, strict_reference
componentname, description, content_type, is_component, current_version_key, nested_schemas
versionversion_number, name, description
resourcename, content_type, document_id, component_key, resource_owner_key, current_revision_key
revisionnumber, size, status, is_valid, version_key
apiname, description, prefix, version, is_auth_required
manageapikey / fluxapikeydescription, public_key, role_key
envrole / fluxrolename, description, full_access
managepermissionrole / fluxpermissionrolerole_key, content_type, actions, all_objects
localecode, name, is_default
GETapi.foxnose.net/v1/:env/events/

List Environment Events

Retrieves events for a specific environment. Returns a paginated list of changes made to environment-scoped entities, ordered by timestamp (newest first by default).

Success Response: 200 OK

Query Parameters

  • Name
    event_type
    Type
    string
    Description

    Filter by event type

    • Values: create, update, delete
    • Operator: exact
  • Name
    entity_type
    Type
    string
    Description

    Filter by entity type

    • Values: folder, resource, revision, component, version, api, manageapikey, fluxapikey, managepermissionrole, fluxpermissionrole, envrole, fluxrole, locale
    • Operator: exact
  • Name
    entity_key
    Type
    string
    Description

    Filter by specific entity key

    • Operator: exact
  • Name
    referer
    Type
    string
    Description

    Filter by HTTP Referer

    • Operator: exact
  • Name
    ip_address
    Type
    string
    Description

    Filter by request IP address

    • Operator: exact
  • Name
    actor_type
    Type
    string
    Description

    Filter by actor type

    • Values: user, apikey
    • Operator: exact
  • Name
    actor_key
    Type
    string
    Description

    Filter by actor key (user key or API key). Requires actor_type.

    • Operator: exact
  • Name
    folder_key
    Type
    string
    Description

    Filter events related to a specific folder

  • Name
    resource_key
    Type
    string
    Description

    Filter events related to a specific resource

  • Name
    schema_key
    Type
    string
    Description

    Filter events related to a specific schema

  • Name
    api_key
    Type
    string
    Description

    Filter events related to a specific Flux API

  • Name
    from_timestamp
    Type
    datetime
    Description

    Filter events from this timestamp (inclusive)

    • Format: ISO 8601 (e.g., 2024-01-15T00:00:00Z)
  • Name
    to_timestamp
    Type
    datetime
    Description

    Filter events until this timestamp (inclusive)

    • Format: ISO 8601 (e.g., 2024-01-15T23:59:59Z)
  • Name
    limit
    Type
    integer
    Default
    default:100
    Description

    Number of events per page

    • Minimum: 1
    • Maximum: 100
  • Name
    offset
    Type
    integer
    Default
    default:0
    Description

    Number of events to skip before starting the page

Ordering

  • Name
    timestamp
    Type
    datetime
    Description

    Order by event timestamp

    • Use ?ordering=timestamp for ascending (oldest first)
    • Use ?ordering=-timestamp for descending (newest first, default)

Errors

  • Name
    401 Unauthorized
    Description

    Authentication credentials are missing or invalid.

    • authentication_failed - authentication credentials were not provided or are invalid
  • Name
    403 Forbidden
    Description

    Insufficient permissions to view events.

    • permission_denied - insufficient permissions to perform this action
  • Name
    404 Not Found
    Description

    The specified resource could not be found. Specific codes:

    • environment_not_found - the specified environment does not exist
    • folder_not_found - the specified folder does not exist
    • resource_not_found - the specified resource does not exist
    • schema_not_found - the specified schema does not exist
    • api_not_found - the specified API does not exist
  • Name
    422 Unprocessable Content
    Description

    Validation error. Specific codes:

    • validation_error - invalid query parameters

Request

GET
/v1/:env/events/
curl https://api.foxnose.net/v1/7c9h4pwu/events/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "timestamp": "2024-01-15T14:30:00Z",
            "event_type": "update",
            "entity_type": "resource",
            "entity_key": "xK9mP2nQvR3s",
            "actor_type": "user",
            "actor": {
                "key": "uS4tV5wX6yZ7",
                "email": "john@example.com",
                "first_name": "John",
                "last_name": "Doe",
                "full_name": "John Doe",
                "deleted_at": null
            },
            "ip_address": "192.168.1.100",
            "referer": "app.foxnose.net",
            "metadata": null
        },
        {
            "key": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
            "timestamp": "2024-01-15T10:15:00Z",
            "event_type": "create",
            "entity_type": "folder",
            "entity_key": "mK8nP3tYvBcX",
            "actor_type": "apikey",
            "actor": {
                "key": "aK1bC2dE3fG4",
                "description": "CI/CD Pipeline Key",
                "public_key": "pk_live_abc123",
                "role": "rL5mN6oP7qR8",
                "created_at": "2024-01-01T00:00:00Z",
                "environment": "7c9h4pwu",
                "deleted_at": null
            },
            "ip_address": "10.0.0.50",
            "referer": null,
            "metadata": null
        }
    ]
}
GETapi.foxnose.net/v1/global-events/

List Global Events

Retrieves organization-level events. Returns a paginated list of changes made to global entities such as users and projects. Requires organization admin access.

Success Response: 200 OK

Query Parameters

  • Name
    event_type
    Type
    string
    Description

    Filter by event type

    • Values: create, update, delete
    • Operator: exact
  • Name
    entity_type
    Type
    string
    Description

    Filter by entity type

    • Values: user, customer, project, environment
    • Operator: exact
  • Name
    entity_key
    Type
    string
    Description

    Filter by specific entity key

    • Operator: exact
  • Name
    referer
    Type
    string
    Description

    Filter by HTTP Referer

    • Operator: exact
  • Name
    actor_key
    Type
    string
    Description

    Filter by user key (global events only). actor_type is not required for global events.

    • Operator: exact
  • Name
    ip_address
    Type
    string
    Description

    Filter by request IP address

    • Operator: exact
  • Name
    project_key
    Type
    string
    Description

    Filter events related to a specific project

  • Name
    from_timestamp
    Type
    datetime
    Description

    Filter events from this timestamp (inclusive)

    • Format: ISO 8601 (e.g., 2024-01-15T00:00:00Z)
  • Name
    to_timestamp
    Type
    datetime
    Description

    Filter events until this timestamp (inclusive)

    • Format: ISO 8601 (e.g., 2024-01-15T23:59:59Z)
  • Name
    limit
    Type
    integer
    Default
    default:100
    Description

    Number of events per page

    • Minimum: 1
    • Maximum: 100
  • Name
    offset
    Type
    integer
    Default
    default:0
    Description

    Number of events to skip before starting the page

Ordering

  • Name
    timestamp
    Type
    datetime
    Description

    Order by event timestamp

    • Use ?ordering=timestamp for ascending (oldest first)
    • Use ?ordering=-timestamp for descending (newest first, default)

Errors

  • Name
    401 Unauthorized
    Description

    Authentication credentials are missing or invalid.

    • authentication_failed - authentication credentials were not provided or are invalid
  • Name
    403 Forbidden
    Description

    Insufficient permissions. Organization admin access required.

    • permission_denied - insufficient permissions to perform this action
  • Name
    404 Not Found
    Description

    The specified resource could not be found. Specific codes:

    • project_not_found - the specified project does not exist
  • Name
    422 Unprocessable Content
    Description

    Validation error. Specific codes:

    • validation_error - invalid query parameters

Request

GET
/v1/global-events/
curl https://api.foxnose.net/v1/global-events/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "timestamp": "2024-01-15T16:45:00Z",
            "event_type": "create",
            "entity_type": "user",
            "entity_key": "uN7oP8qR9sT0",
            "actor_type": "user",
            "actor": {
                "key": "uS4tV5wX6yZ7",
                "email": "admin@example.com",
                "first_name": "Admin",
                "last_name": "User",
                "full_name": "Admin User",
                "deleted_at": null
            },
            "ip_address": "192.168.1.1",
            "referer": "app.foxnose.net",
            "metadata": null
        },
        {
            "key": "d4e5f6a7-b8c9-0123-defa-456789012345",
            "timestamp": "2024-01-14T09:30:00Z",
            "event_type": "update",
            "entity_type": "project",
            "entity_key": "pR3jK4tL5mN6",
            "actor_type": "user",
            "actor": {
                "key": "uS4tV5wX6yZ7",
                "email": "admin@example.com",
                "first_name": "Admin",
                "last_name": "User",
                "full_name": "Admin User",
                "deleted_at": null
            },
            "ip_address": "192.168.1.1",
            "referer": "app.foxnose.net",
            "metadata": null
        }
    ]
}

Was this page helpful?