T
testing
API Reference: Integrations & Infrastructure Tracking Project Events via API

The Events API provides a complete audit trail of system activities and user actions within your projects. Use these endpoints to monitor what's happening, log custom events, and integrate with real-time push notifications.

Push Notifications

Retrieve VAPID keys to enable real-time Web Push alerts for your events.

sequenceDiagram
    participant Client
    participant API as Events API
    participant DB as Event Log
    
    Client->>API: POST /events (Create)
    API->>DB: Store Event
    API-->>Client: 201 Created
    
    Client->>API: GET /events (List)
    DB-->>API: Retrieve Events
    API-->>Client: 200 OK (Event List)

Standard Endpoints

The standard approach to managing events requires your organization_id and project_id in the URL path. This ensures proper scoping and security when your API token has access to multiple projects.

ActionMethodEndpoint
List eventsGET/v1/organizations/{organization_id}/projects/{project_id}/events
Create eventPOST/v1/organizations/{organization_id}/projects/{project_id}/events

Example: Retrieving events

To fetch a list of recent events for a specific project, attach your Bearer token and call the GET endpoint:

curl -X GET "https://api.gitdocai.com/v1/organizations/org_123/projects/proj_456/events" 
  -H "Authorization: Bearer YOUR_API_TOKEN"

Tracking a Custom Event

You can log custom actions—like a user completing a specific workflow or a background job finishing—directly to the event log.

  1. 1

    Gather your IDs

    Locate your organization_id and project_id from your dashboard settings or via the Projects API.

  2. 2

    Prepare the payload

    Create a JSON body containing the event details, such as the event name, description, and any custom metadata you want to track.

  3. 3

    Send the request

    Make a POST request to the standard events endpoint to record the action permanently in your project's history.

Simplified Endpoints

If your application uses scoped API tokens that already contain organization and project context, you can use our simplified endpoints. These omit the lengthy ID paths.

ActionMethodEndpoint
List eventsPOST/v1/event/list
Delete eventDELETE/v1/event

Notice that the simplified list endpoint uses a POST method instead of GET. This allows you to pass complex filtering, sorting, and pagination parameters securely in the request body rather than as URL query strings.

Push Notifications (VAPID)

If you are building a web application and want to subscribe users to real-time event notifications via Web Push, you will need our VAPID public key.

Endpoint: GET /v1/event/vapid-public-key

VAPID (Voluntary Application Server Identification) keys allow your client application to verify that push messages are genuinely originating from our API, keeping your users secure from spoofed notifications.

Frequently Asked Questions

When should I use the simplified endpoints?

Use simplified endpoints when your API token is strictly scoped to a single project. If you are managing multiple projects or using an organization-wide token, you must use the standard endpoints to explicitly define the target project.

Can I recover a deleted event?

No. Deleting an event via the DELETE endpoint is a permanent action. If you need to maintain a strict audit trail for compliance reasons, we recommend filtering out events in your UI rather than deleting them from the API.