Tracking project events helps you monitor activity, trigger automated workflows, and keep your external systems in sync. The Events API provides a set of endpoints to create, list, and delete event records, as well as retrieve VAPID keys for secure web push notifications.
Depending on your integration needs, you can use the Standard Endpoints (which require explicit organization and project IDs in the URL) or the Simplified Endpoints (which infer the context from your authentication token).
sequenceDiagram
participant App as Your Application
participant API as Events API
App->>API: POST /v1/.../events (Create Event)
API-->>App: 201 Created
App->>API: GET /v1/.../events (List Events)
API-->>App: 200 OK (List of Events)
App->>API: DELETE /v1/.../events/{id} (Delete Event)
API-->>App: 204 No ContentAll requests to the Events API require a valid Bearer token in the Authorization header.
Standard Endpoints
Standard endpoints are best suited for backend integrations and administrative tools where you need to manage events across multiple organizations or projects.
| Action | Method | Endpoint |
|---|---|---|
| Create | POST | /v1/organizations/{organization_id}/projects/{project_id}/events |
| List | GET | /v1/organizations/{organization_id}/projects/{project_id}/events |
| Delete | DELETE | /v1/organizations/{organization_id}/projects/{project_id}/events/{event_id} |
Creating an event
To log a new event, send a POST request to the standard events endpoint. This is useful for recording custom activities, build statuses, or user actions within a specific project.
curl -X POST "https://api.gitdocai.com/v1/organizations/org_123/projects/proj_456/events"
-H "Authorization: Bearer YOUR_API_TOKEN"
-H "Content-Type: application/json"
-d '{
"type": "build_started",
"description": "Triggered production build"
}'Listing events
Retrieve a history of events for a specific project using the GET endpoint.
curl -X GET "https://api.gitdocai.com/v1/organizations/org_123/projects/proj_456/events"
-H "Authorization: Bearer YOUR_API_TOKEN"Event lists are typically returned in reverse chronological order (newest first). If your project generates a high volume of events, be sure to implement pagination in your application.
Simplified Endpoints
Simplified endpoints offer a shorter URL structure. They are ideal for client-side applications or scoped API tokens where the project context is already known.
| Action | Method | Endpoint |
|---|---|---|
| List | POST | /v1/event/list |
| Delete | DELETE | /v1/event |
| VAPID Key | GET | /v1/event/vapid-public-key |
Notice that the simplified list endpoint uses a POST method instead of GET. This allows you to pass complex filtering and sorting parameters securely in the request body.
Setting Up Push Notifications
If you want to receive real-time updates when events occur, you can use Web Push Notifications. To securely subscribe a client to these notifications, you will need our VAPID (Voluntary Application Server Identification) public key.
- 1
Retrieve the VAPID Public Key
Call the VAPID endpoint to get the public key required for the push subscription.
curl -X GET "https://api.gitdocai.com/v1/event/vapid-public-key" -H "Authorization: Bearer YOUR_API_TOKEN" - 2
Subscribe the Client
Use the retrieved public key in your frontend application to subscribe the user's browser to your push service.
- 3
Handle Incoming Events
Listen for push events in your service worker to display notifications or trigger background updates when new project events occur.
Frequently Asked Questions
Should I use the Standard or Simplified endpoints?
Use Standard endpoints if your application manages multiple projects or organizations and you have a global API key. Use Simplified endpoints if your application operates entirely within the context of a single project (e.g., a project-scoped frontend dashboard).
How do I delete an event using the simplified endpoint?
Because the simplified DELETE /v1/event endpoint doesn't include the event ID in the URL path, you must provide the target event's identifier in the request body or as a query parameter, depending on your specific client configuration.