> ## Documentation Index
> Fetch the complete documentation index at: https://quintsecurity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Event ingestion and querying

# Events API

The events API handles ingestion of agent activity captured by the Quint daemon, and provides querying capabilities for event data.

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /v1/events/ingest" href="/api/endpoint/post-events-ingest">
    Daemon event ingestion (rate-limited). Used by the Quint daemon to push captured events.
  </Card>

  <Card title="GET /v1/events" href="/api/endpoint/get-events">
    List events with filtering by agent, session, action type, tool name, decision, risk range, and time range.
  </Card>

  <Card title="GET /v1/events/stats" href="/api/endpoint/get-events-stats">
    24-hour aggregate statistics across events.
  </Card>

  <Card title="GET /v1/events/{id}" href="/api/endpoint/get-event-detail">
    Retrieve a single event by ID.
  </Card>
</CardGroup>

## Event Schema

Events are captured at the OS level by the Quint daemon. Each event represents a single system action performed by (or on behalf of) an AI agent:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "agent_id": "claude-code",
  "action_type": "PROCESS_EXEC",
  "tool_name": "git",
  "arguments": ["commit", "-m", "Fix auth bug"],
  "risk_score": 12,
  "decision": "allow",
  "timestamp": "2026-04-12T14:32:00Z"
}
```

<Note>
  `risk_score` is a shadow-mode corroborating signal, not the enforcement decision. Enforcement is deterministic scope evaluation; a block fires on a scope violation against a sensitive resource, and `min_risk`/`max_risk` filter on the corroborating signal only.
</Note>

## Action Types

Events are categorized by what the agent did at the OS level:

| Action Type       | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `PROCESS_EXEC`    | Agent spawned a child process (e.g., `git`, `npm`, `curl`) |
| `FILE_READ`       | Agent read a file from disk                                |
| `FILE_WRITE`      | Agent wrote or modified a file                             |
| `FILE_DELETE`     | Agent deleted a file                                       |
| `NETWORK_CONNECT` | Agent made an outbound network connection                  |

## Filtering

The `GET /v1/events` endpoint supports query parameters for filtering:

```bash theme={null}
# Events from a specific agent
curl "https://api.quintai.dev/v1/events?agent_id=claude-code" \
  -H "Authorization: Bearer qt_deploy_YOUR_TOKEN"

# Process executions in a specific session
curl "https://api.quintai.dev/v1/events?session_id=SESSION_UUID&action_type=PROCESS_EXEC" \
  -H "Authorization: Bearer qt_deploy_YOUR_TOKEN"

# High-risk events by tool
curl "https://api.quintai.dev/v1/events?tool_name=curl&min_risk=50&max_risk=100" \
  -H "Authorization: Bearer qt_deploy_YOUR_TOKEN"

# Events in a time range
curl "https://api.quintai.dev/v1/events?since=2026-04-11T00:00:00Z&end_time=2026-04-12T00:00:00Z" \
  -H "Authorization: Bearer qt_deploy_YOUR_TOKEN"
```

## Data Model

```mermaid theme={null}
erDiagram
    organizations ||--o{ deploy_tokens : "has"
    organizations ||--o{ sessions : "owns"
    organizations ||--o{ events : "owns"
    sessions ||--o{ events : "contains"
    sessions ||--o{ sessions : "parent/child"
    events }o--|| agents : "triggered by"

    organizations {
        uuid id PK
        string name
        timestamp created_at
    }
    deploy_tokens {
        uuid id PK
        uuid org_id FK
        string name
        string token_hash
        timestamp created_at
    }
    sessions {
        uuid id PK
        uuid org_id FK
        uuid parent_id FK
        string session_name
        string model
        string signing_id
        string state
        string platform
        timestamp started_at
        timestamp ended_at
    }
    events {
        uuid id PK
        uuid org_id FK
        uuid session_id FK
        string agent_id
        string action_type
        string tool_name
        jsonb arguments
        int risk_score
        string decision
        timestamp timestamp
    }
    agents {
        string id PK
        string platform
        string signing_id
        timestamp first_seen
        timestamp last_seen
    }
```

## Session Linkage

Every event carries a `session_id` (UUID v5) that links it to an agent session. Sessions are tracked separately via the [Sessions API](/api/sessions), providing hierarchical grouping of events with parent/child relationships.