T
testing
API Reference: Integrations & Infrastructure Administering Customers via API

Welcome to the Customer Administration API documentation. As an administrator, you can use these endpoints to oversee customer organizations, monitor system events, and manage infrastructure integrations like Git providers.

Whether you are building an internal dashboard or automating your administrative workflows, this guide will help you navigate the available resources.

Customer Admin

Manage and export organization data.

System Events

Track and trigger project notifications.

Infrastructure

Manage Git OAuth and S2S operations.

Customer Administration

The customer administration endpoints allow you to retrieve high-level overviews of the organizations using your platform.

MethodEndpointDescription
GET/v1/admin/customersRetrieves a paginated list of all customer organizations.
GET/v1/admin/customers/{organization_id}Retrieves detailed overview metrics for a specific customer.
GET/v1/admin/customers/exportGenerates and downloads a CSV export of all customer data.

Exporting Customer Data

If you need to analyze customer data in external tools like Excel or a BI platform, you can easily export your customer list.

  1. 1

    Authenticate as an Admin

    Ensure your API request includes a bearer token belonging to a user with admin privileges.

  2. 2

    Request the Export

    Call the export endpoint to generate the CSV file.

    curl -X GET https://api.gitdocai.com/v1/admin/customers/export 
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" 
  -o customers_export.csv
  3. 3

    Process the Data

    The system will return a standard CSV file containing organization IDs, names, subscription statuses, and creation dates.

Organization Management

These endpoints allow you to manage individual organizations, including creation, configuration, and onboarding processes.

MethodEndpointDescription
GET/v1/organizationGet all organizations for the current user.
POST/v1/organizationCreate a new organization.
GET/v1/organization/{organization_id}Get an organization by its ID.
PUT/v1/organization/{organization_id}Update an organization.
DELETE/v1/organization/{organization_id}Delete an organization.
POST/v1/organization/{organization_id}/complete-onboardingComplete the onboarding process for an organization.
POST/v1/organization/{organization_id}/upload-logoUpload an organization logo.
GET/v1/organization/allList all organizations (admin only).

Event Management

Events are used to track activities, trigger webhooks, and send push notifications. The API provides both strictly scoped endpoints (requiring organization and project IDs) and simplified endpoints for quicker access.

flowchart LR
    A["Organization"] --> B["Project"]
    B --> C["Event 1"]
    B --> D["Event 2"]
    B --> E["Event 3"]
    
    style A fill:#f9f9f9,stroke:#333,stroke-width:2px
    style B fill:#e1f5fe,stroke:#0288d1,stroke-width:2px

Scoped Event Endpoints

Use these endpoints when you are managing events within a specific project context:

  • GET /v1/organizations/{organization_id}/projects/{project_id}/events — List all events for a project.

  • POST /v1/organizations/{organization_id}/projects/{project_id}/events — Create a new event.

  • DELETE /v1/organizations/{organization_id}/projects/{project_id}/events/{event_id} — Delete a specific event.

Simplified Event Endpoints

For global operations or when the project context is already inferred by the authentication token:

  • POST /v1/event/list — List events.

  • DELETE /v1/event — Delete an event.

  • GET /v1/event/vapid-public-key — Retrieve the VAPID public key.

What is a VAPID key?
The /v1/event/vapid-public-key endpoint is used for Web Push notifications. Voluntary Application Server Identification (VAPID) allows your client applications to securely subscribe to push events generated by the platform.

Git Provider Integration

When connecting external Git providers (like GitHub or GitLab), the platform uses OAuth to securely grant access to repositories.

MethodEndpointDescription
POST/v1/organizations/{organization_id}/git-provider/callbackHandles the OAuth callback from the Git provider after a user authorizes the application.
GET/v1/organizations/{organization_id}/git-provider/repositories/{repository_id}/treeRetrieves the file tree structure for a connected repository.

You rarely need to call the callback endpoint manually. It is typically registered as the Redirect URI in your Git provider's OAuth application settings and handled automatically by the browser flow.

Internal Operations

Internal endpoints are reserved for system-level operations and microservice communication.

MethodEndpointDescription
POST/internal/subscriptions/{organization_id}/toggle-activeToggles the active documentation subscription status for an organization.

Service-to-Service (S2S) Only
Endpoints prefixed with /internal/ cannot be called using standard user or admin bearer tokens. They require a dedicated S2S authentication token and are restricted to internal network traffic.

Frequently Asked Questions

Why am I getting a 403 Forbidden on the /v1/admin endpoints?

The /v1/admin/* endpoints strictly require global administrator privileges. Standard organization owners or project admins will receive a 403 status code. Verify that your API token is generated from a global admin account.

Should I use the simplified or scoped event endpoints?

If your application manages multiple organizations or projects, always use the scoped endpoints (/v1/organizations/...) to prevent accidental data leakage or modification. Use the simplified endpoints (/v1/event/...) only in single-tenant environments or when using strictly scoped API keys.