Managing Usage Limits via API

Manage and monitor your organization's subscription limits programmatically using the Subscription API. These endpoints allow you to check if specific features are enabled for your tier and validate whether your current usage permits further actions, ensuring your application stays within its allocated quotas.

Before you begin, you will need your organization_id and a valid API key to authenticate your requests.

Need an API Key?

Learn how to generate and manage your API keys in the Authentication guide.

Understanding the Subscription Endpoints

We provide three primary endpoints to help you manage usage and feature access. Depending on what you are trying to build, you can check boolean access, retrieve raw limit values, or validate usage caps.

Goal	Endpoint	Method
Check if a feature is enabled	`/organization/{organization_id}/subscription/validate-feature`	`GET`
Get the exact limit value	`/organization/{organization_id}/subscription/feature-value`	`GET`
Check if usage allows an action	`/organization/{organization_id}/subscription/validate-limit`	`GET`

Never hardcode subscription limits directly into your application. Always query these endpoints to ensure your app dynamically respects the user's current billing tier and any custom negotiated limits.

Implementation Workflow

When building features that consume resources (like adding new team members or creating new documents), you should validate the organization's limits before processing the action.

Here is the recommended flow for enforcing usage limits:

sequenceDiagram
    participant Client
    participant YourApp as Your Application
    participant API as GitDocAI API

    Client->>YourApp: Trigger resource creation
    YourApp->>API: GET /subscription/validate-limit
    
    alt Limit not reached
        API-->>YourApp: Allowed (200 OK)
        YourApp->>YourApp: Process creation
        YourApp-->>Client: Success response
    else Limit reached
        API-->>YourApp: Denied (403 Forbidden / Quota Exceeded)
        YourApp-->>Client: Prompt to upgrade subscription
    end

Step-by-Step Integration

Verify feature access

Before showing a premium feature in your UI, check if the organization's subscription tier includes it.

curl -X GET "https://api.gitdocai.com/organization/org_12345/subscription/validate-feature?feature=advanced_analytics" 
  -H "Authorization: Bearer YOUR_API_KEY"

Display usage metrics (Optional)

If you want to show users a progress bar of their usage (e.g., "4 of 5 seats used"), retrieve the exact feature value limit.

curl -X GET "https://api.gitdocai.com/organization/org_12345/subscription/feature-value?feature=team_seats" 
  -H "Authorization: Bearer YOUR_API_KEY"

Validate limits before execution

Right before executing a resource-intensive action, validate that the organization has enough capacity left.

curl -X GET "https://api.gitdocai.com/organization/org_12345/subscription/validate-limit?feature=team_seats" 
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Cache feature flags
To reduce API calls and improve your application's performance, cache the results of validate-feature for a short period (e.g., 5-15 minutes). Feature access rarely changes second-to-second.

If you make too many requests to the Subscription API, you will receive a 429 Too Many Requests response. We recommend implementing exponential backoff in your application to handle these scenarios gracefully.

Currently, the endpoints are designed to evaluate one specific feature or limit per request. If you need to validate multiple features, you will need to make separate API calls.