Credits

Important Notice

All Credits endpoints are not compatible with legacy plans. Requests from teams with this legacy plan version will receive a 400 error response

{
    "error": "This endpoint is not available for teams that have a legacy plan"
}

Get Subscription Info

This endpoint makes an HTTP GET request to retrieve comprehensive subscription information for a team, including credit balance, addons, and subscription details.

Request

Method: GET
Endpoint: https://api.thebrief.ai/v1/credits/subscription-info
Query Parameters:
- teamId (integer, required): The ID of the team to retrieve subscription information for.

curl --location 'https://api.thebrief.ai/v1/credits/subscription-info?teamId=12345' \
--header 'Authorization: Bearer eyJh...'

Response

Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure:

{
    "response": {
        "id": 0,
        "planCode": "",
        "planVersion": "",
        "currentPeriodStartedAt": "",
        "currentPeriodEndsAt": "",
        "addons": [
            {
                "id": 0,
                "code": "",
                "name": "",
                "type": "",
                "quantity": 0,
                "unitAmountInCents": 0,
                "createdAt": "",
                "updatedAt": ""
            }
        ],
        "creditBalance": {
            "availableRecurringCredits": 0,
            "availableRollingCredits": 0,
            "availableTopUpCredits": 0,
            "lockedRecurringCredits": 0,
            "lockedRollingCredits": 0,
            "lockedTopUpCredits": 0,
            "totalAvailableCredits": 0,
            "totalLockedCredits": 0,
            "consumedRecurringCredits": 0,
            "consumedRollingCredits": 0,
            "consumedTopUpCredits": 0,
            "totalConsumedCredits": 0,
            "dailyConsumedCredits": 0,
            "creditsLimit": {
                "recurringCredits": 0,
                "rollingCredits": 0,
                "topUpCredits": 0
            }
        }
    }
}

Response Fields:

id: The subscription ID
planCode: The current plan code (e.g., "pro_monthly", "enterprise_yearly")
planVersion: The version of the plan
currentPeriodStartedAt: ISO 8601 timestamp when the current billing period started
currentPeriodEndsAt: ISO 8601 timestamp when the current billing period ends
addons: Array of subscription addons
- id: Addon ID
- code: Addon code
- name: Human-readable addon name
- type: Addon type (e.g., "recurring", "one_time")
- quantity: Quantity of the addon
- unitAmountInCents: Cost per unit in cents
- createdAt: ISO 8601 timestamp when addon was created
- updatedAt: ISO 8601 timestamp when addon was last updated
creditBalance: Detailed breakdown of credit balance
- availableRecurringCredits: Available credits from recurring subscription
- availableRollingCredits: Available credits that roll over
- availableTopUpCredits: Available credits from top-up purchases
- lockedRecurringCredits: Locked recurring credits (reserved for ongoing operations)
- lockedRollingCredits: Locked rolling credits
- lockedTopUpCredits: Locked top-up credits
- totalAvailableCredits: Sum of all available credits
- totalLockedCredits: Sum of all locked credits
- consumedRecurringCredits: Consumed recurring credits in current period
- consumedRollingCredits: Consumed rolling credits
- consumedTopUpCredits: Consumed top-up credits
- totalConsumedCredits: Sum of all consumed credits
- dailyConsumedCredits: Credits consumed today
- creditsLimit: Overall credit limits for the subscription

Example Response:

{
    "response": {
        "id": 12345,
        "planCode": "pro_monthly",
        "planVersion": "v2",
        "currentPeriodStartedAt": "2024-01-01T00:00:00.000Z",
        "currentPeriodEndsAt": "2024-02-01T00:00:00.000Z",
        "addons": [
            {
                "id": 1,
                "code": "extra_credits",
                "name": "Extra Credits",
                "type": "recurring",
                "quantity": 1000,
                "unitAmountInCents": 5000,
                "createdAt": "2024-01-01T00:00:00.000Z",
                "updatedAt": "2024-01-01T00:00:00.000Z"
            }
        ],
        "creditBalance": {
            "availableRecurringCredits": 500,
            "availableRollingCredits": 200,
            "availableTopUpCredits": 100,
            "lockedRecurringCredits": 50,
            "lockedRollingCredits": 20,
            "lockedTopUpCredits": 10,
            "totalAvailableCredits": 800,
            "totalLockedCredits": 80,
            "consumedRecurringCredits": 450,
            "consumedRollingCredits": 180,
            "consumedTopUpCredits": 90,
            "totalConsumedCredits": 720,
            "dailyConsumedCredits": 25,
            "creditsLimit": {
                "recurringCredits": 1000,
                "rollingCredits": 500,
                "topUpCredits": 200
            }
        }
    }
}

Get Team Consumption Report

This endpoint makes an HTTP GET request to retrieve a detailed consumption report for a team, including breakdown by users and features for a specified time period.

Request

Method: GET
Endpoint: https://api.thebrief.ai/v1/credits/team-consumption-report
Query Parameters:
- teamId (integer, required): The ID of the team to retrieve the consumption report for.
- startDate (string, required): Start date for the report period in ISO 8601 format (e.g., "2024-01-01T00:00:00.000Z")
- endDate (string, required): End date for the report period in ISO 8601 format (e.g., "2024-12-31T23:59:59.999Z")
- userIds (string, optional): Comma-separated list of user IDs to filter the report by specific users (e.g., "101,102,103")
- creditOperationIds (string, optional): Comma-separated list of credit operation IDs to filter by specific operations (e.g., "1,2,3")

curl --location 'https://api.thebrief.ai/v1/credits/team-consumption-report?teamId=12345&startDate=2024-01-01T00:00:00.000Z&endDate=2024-12-31T23:59:59.999Z&userIds=101,102,103' \
--header 'Authorization: Bearer eyJh...'

Response

Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure:

{
    "response": {
        "totalTeamConsumption": 0,
        "breakdownByUsers": [
            {
                "userId": 0,
                "totalUserConsumption": 0,
                "breakdownByFeatures": [
                    {
                        "featureName": "",
                        "featureType": "",
                        "credits": 0
                    }
                ]
            }
        ]
    }
}

Response Fields:

totalTeamConsumption: Total credits consumed by the entire team during the specified period
breakdownByUsers: Array of consumption data per user
- userId: The ID of the user
- totalUserConsumption: Total credits consumed by this user
- breakdownByFeatures: Array of consumption data per feature for this user
  - featureName: Human-readable name of the feature (e.g., "AI Image Generation", "Design Export")
  - featureType: Type identifier of the feature (e.g., "ai_generation", "export", "video_export")
  - credits: Number of credits consumed for this feature

Example Response:

{
    "response": {
        "totalTeamConsumption": 1250,
        "breakdownByUsers": [
            {
                "userId": 101,
                "totalUserConsumption": 500,
                "breakdownByFeatures": [
                    {
                        "featureName": "AI Image Generation",
                        "featureType": "ai_generation",
                        "credits": 300
                    },
                    {
                        "featureName": "Design Export",
                        "featureType": "export",
                        "credits": 200
                    }
                ]
            },
            {
                "userId": 102,
                "totalUserConsumption": 750,
                "breakdownByFeatures": [
                    {
                        "featureName": "AI Image Generation",
                        "featureType": "ai_generation",
                        "credits": 450
                    },
                    {
                        "featureName": "Video Export",
                        "featureType": "video_export",
                        "credits": 300
                    }
                ]
            }
        ]
    }
}

Use Cases:

Analyze team credit consumption over a specific period
Track individual user consumption patterns
Identify which features consume the most credits
Generate billing reports and usage analytics
Monitor credit usage trends for capacity planning

List Credit Operations

This endpoint makes an HTTP GET request to retrieve all available credit operations with their associated costs. This is useful for understanding how many credits each feature operation consumes.

Request

Method: GET
Endpoint: https://api.thebrief.ai/v1/credits/operations
Query Parameters: None

curl --location 'https://api.thebrief.ai/v1/credits/operations' \
--header 'Authorization: Bearer eyJh...'

Response

Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure:

{
    "response": {
        "operations": [
            {
                "id": 0,
                "featureName": "",
                "featureType": "",
                "cost": 0
            }
        ]
    }
}

Response Fields:

operations: Array of credit operations
- id: Unique identifier for the operation
- featureName: Human-readable name of the feature (e.g., "AI Image Generation", "Design Export")
- featureType: Type identifier of the feature (e.g., "ai_generation", "export", "video_export")
- cost: Number of credits consumed per operation

Example Response:

{
    "response": {
        "operations": [
            {
                "id": 1,
                "featureName": "AI Image Generation",
                "featureType": "ai_generation",
                "cost": 10
            },
            {
                "id": 2,
                "featureName": "Design Export",
                "featureType": "export",
                "cost": 5
            },
            {
                "id": 3,
                "featureName": "Video Export",
                "featureType": "video_export",
                "cost": 15
            },
            {
                "id": 4,
                "featureName": "AI Text Generation",
                "featureType": "ai_text",
                "cost": 8
            },
            {
                "id": 5,
                "featureName": "Background Removal",
                "featureType": "background_removal",
                "cost": 12
            }
        ]
    }
}

Use Cases:

Display credit costs to users before they perform operations
Calculate estimated costs for bulk operations
Build custom pricing calculators
Integrate cost information into your application's UI
Monitor changes in operation costs over time

Authentication

All Credits endpoints require authentication using a Bearer token in the Authorization header:

--header 'Authorization: Bearer YOUR_API_TOKEN'

To obtain an API token, please refer to the Authentication section of the documentation.

Error Responses

All endpoints may return the following error responses:

400 Bad Request

Returned when required parameters are missing or invalid.

{
    "error": "Missing teamId parameter"
}

{
    "error": "Invalid teamId parameter"
}

401 Unauthorized

Returned when the authentication token is missing or invalid.

{
    "error": "Unauthorized"
}

403 Forbidden

Returned when the authenticated user doesn't have access to the requested team.

{
    "error": "You don't have access to this team"
}

500 Internal Server Error

Returned when an unexpected error occurs on the server.

{
    "error": "Failed to fetch subscription info"
}

{
    "error": "Failed to fetch team consumption report"
}

{
    "error": "Failed to fetch credit operations"
}

Rate Limiting

These endpoints are subject to the standard API rate limits. Please refer to the main API documentation for current rate limit policies.

PreviousDesign Fonts NextGraphQL

Last updated 1 month ago