T
testing
API Reference: Integrations & Infrastructure Managing Push Notifications via API

Programmatically manage push notifications to keep your users engaged and informed. This guide walks you through subscribing devices to receive notifications, as well as managing related infrastructure like direct file uploads and user onboarding progress.

Authentication Required

All endpoints in this guide require a valid API key. Ensure you include your Bearer token in the Authorization header of every request.

Push Notification Subscriptions

To send push notifications to a user's device, you first need to register their device token with our system. We provide two endpoints for this depending on your architectural needs.

Subscription Flow

sequenceDiagram
    participant App as Client Application
    participant API as GitDocAI API
    participant Push as Push Service (APNs/FCM)
    
    App->>Push: Request Device Token
    Push-->>App: Return Device Token
    App->>API: POST /push/subscribe (Send Token)
    API-->>App: 200 OK (Subscription Active)
    Note over API,Push: API can now route futurenotifications to this device

Available Endpoints

EndpointMethodUse Case
/v1/event/push-notification-subscribePOSTSimplified: Best for global or user-level subscriptions where organization context isn't required.
/v1/organizations/{organization_id}/push/subscribePOSTOrg-Scoped: Best for multi-tenant applications where notifications must be strictly isolated by organization.

Which should I use? If your application relies heavily on Organization IDs for data access and permissions, use the Org-Scoped endpoint to ensure notifications are properly siloed.

Example Request:

curl -X POST https://api.gitdocai.com/v1/organizations/org_12345/push/subscribe 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "device_token": "abc123xyz890",
    "platform": "ios"
  }'

Managing File Resources

Often, push notifications are triggered by document updates or file uploads. Our infrastructure supports secure, direct-to-cloud file uploads.

Uploading a file is a two-step process to ensure security and data integrity:

  1. 1

    Request a Signed Upload URL

    Call POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/upload-url. This endpoint returns a secure, time-limited URL that allows your client to upload a file directly to our storage buckets without passing the heavy payload through our API.

  2. 2

    Upload the File

    Use the provided URL from Step 1 to PUT your file directly to the storage provider.

  3. 3

    Finalize the Upload

    Once the upload is complete, call POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/finalize. This tells our system to verify the file, process it, and make it available in your documentation repository.

Signed URLs typically expire within 15 minutes. Ensure your client application begins the upload immediately after requesting the URL.

Importing Assets from URLs

If you need to pull in an asset from an external source rather than uploading it directly, you can import it via URL.

POST /v1/documentation/{organization_id}/{documentation_id}/asset/import
Imports an asset from a provided URL directly into your documentation repository.

Tracking Wizard Progress

If you are using push notifications to guide users through an onboarding flow or a documentation wizard, you can programmatically track their progress using the Wizard Progress API.

Get Wizard Progress

GET /v1/organization/{organization_id}/wizard-progress/{documentation_id}

Retrieves the current state of a user's onboarding wizard. Use this to determine where a user left off so you can send a targeted push notification (e.g., "Don't forget to finish setting up your profile!").

Upsert Wizard Progress

POST /v1/organization/{organization_id}/wizard-progress/{documentation_id}

Creates or updates the progress record. Call this endpoint whenever a user completes a step in your UI.

Delete Wizard Progress

DELETE /v1/organization/{organization_id}/wizard-progress/{documentation_id}

Clears the progress record. This is useful if a user wants to restart a tutorial or if you need to reset their state for testing purposes.

Managing Organization Subscriptions

You can programmatically check an organization's subscription limits and feature availability to ensure they have access to specific infrastructure capabilities.

EndpointMethodDescription
/organization/{organization_id}/subscription/feature-valueGETRetrieves the specific value configured for a subscription feature.
/organization/{organization_id}/subscription/validate-featureGETValidates whether a specific feature is enabled for the organization.
/organization/{organization_id}/subscription/validate-limitGETChecks if the organization's current usage allows for more capacity under their feature limit.

Search and Content Retrieval

Integrate documentation search and raw content retrieval directly into your applications.

EndpointMethodDescription
/documentations/{organization_id}/{documentation_id}/searchPOSTExecutes a search query across the specified documentation.
/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}/section/{section_id}/sourceGETRetrieves the raw source content for a specific documentation section.