openapi: 3.0.3
info:
  title: GC AI External Chat Usage API
  version: 1.0.0
  description: 'The GC AI External API allows programmatic access to GC AI''s chat capabilities. It''s designed for integration with workflow automation tools like Zapier, Make, n8n, or custom applications.


    ## Authentication


    All API requests must include an API key in the `Authorization` header:


    ```

    Authorization: gcai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    ```


    API keys can be created in the GC AI app under **Settings → API**.


    ## Multi-turn Conversations


    Conversations can span multiple turns: pass the `chat_id` returned by a completion back on your next request to continue the same chat. See [Multi-turn Conversations](/api-reference/concepts/multi-turn).


    ## Current Limitations


    The following is not yet available via API:


    - **Interactive clarification**: the model cannot pause to ask the caller a follow-up question; the `askUserQuestions` tool is disabled on the API surface in beta


    ## Usage


    Usage is tracked and viewable in the GC AI app under **Settings → API → View Usage**.


    ## Support


    For API support, contact [support@gc.ai](mailto:support@gc.ai) or reach out to your account representative.'
  contact:
    email: support@gc.ai
servers:
- url: https://app.gc.ai/api/external/v1
  description: Production server
tags:
- name: Usage
  description: Usage and credit/billing reporting endpoints
paths:
  /credit-usage:
    get:
      summary: Get credit usage
      description: 'Billing view of the organization''s credit consumption, broken down by billable operation and by day, with rate-card pricing.


        Requires an org-scoped API key — credit usage is an organization-level concern. User-scoped keys receive a 403.


        If rate-card pricing can''t be resolved for every observed operation, `pricing_available` is `false` and all credit fields are null; raw request counts are still returned.'
      operationId: getCreditUsage
      tags:
      - Usage
      security:
      - ApiKeyAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Inclusive range start (`YYYY-MM-DD`).
          example: 2026-06-01
        required: true
        description: Inclusive range start (`YYYY-MM-DD`).
        name: start_date
        in: query
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Inclusive range end (`YYYY-MM-DD`).
          example: 2026-06-30
        required: true
        description: Inclusive range end (`YYYY-MM-DD`).
        name: end_date
        in: query
      - schema:
          type: string
          default: UTC
          description: IANA timezone for day boundaries (default `UTC`), e.g. `America/New_York`.
        required: false
        description: IANA timezone for day boundaries (default `UTC`), e.g. `America/New_York`.
        name: timezone
        in: query
      responses:
        '200':
          description: Credit usage for the requested range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditUsageResponse'
        '400':
          description: Invalid date range or timezone (bad calendar date, end before start, unknown timezone, or range over 366 days)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or malformed API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Credit usage requires an org-scoped API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying after a rate-limit block.
                example: '60'
              required: true
              description: Seconds to wait before retrying after a rate-limit block.
            RateLimit-Limit:
              schema:
                type: string
                description: Request quota for the applicable window.
                example: '3'
              required: true
              description: Request quota for the applicable window.
            RateLimit-Remaining:
              schema:
                type: string
                description: Requests remaining in the current window.
                example: '0'
              required: true
              description: Requests remaining in the current window.
            RateLimit-Reset:
              schema:
                type: string
                description: Seconds until the quota resets.
                example: '60'
              required: true
              description: Seconds until the quota resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying after a transient service outage.
                example: '5'
              required: true
              description: Seconds to wait before retrying after a transient service outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /usage:
    get:
      summary: Get usage summary
      description: 'Organization-wide product-usage summary by channel: `web` (web app), `word` (Word add-in), and `api`.


        Requires an org-scoped API key — usage is reported org-wide, so a user-scoped key receives a 403. For credit/billing totals, use `GET /v1/credit-usage`.


        Note: web/word counts are sourced from product analytics; day boundaries for those channels are approximate (UTC).'
      operationId: getUsage
      tags:
      - Usage
      security:
      - ApiKeyAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Inclusive range start (`YYYY-MM-DD`).
          example: 2026-06-01
        required: true
        description: Inclusive range start (`YYYY-MM-DD`).
        name: start_date
        in: query
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Inclusive range end (`YYYY-MM-DD`).
          example: 2026-06-30
        required: true
        description: Inclusive range end (`YYYY-MM-DD`).
        name: end_date
        in: query
      - schema:
          type: string
          default: UTC
          description: IANA timezone for the api channel day boundaries (default `UTC`).
        required: false
        description: IANA timezone for the api channel day boundaries (default `UTC`).
        name: timezone
        in: query
      responses:
        '200':
          description: Usage summary for the requested range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummaryResponse'
        '400':
          description: Invalid date range or timezone (bad calendar date, end before start, unknown timezone, or range over 366 days)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or malformed API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Usage requires an org-scoped API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying after a rate-limit block.
                example: '60'
              required: true
              description: Seconds to wait before retrying after a rate-limit block.
            RateLimit-Limit:
              schema:
                type: string
                description: Request quota for the applicable window.
                example: '3'
              required: true
              description: Request quota for the applicable window.
            RateLimit-Remaining:
              schema:
                type: string
                description: Requests remaining in the current window.
                example: '0'
              required: true
              description: Requests remaining in the current window.
            RateLimit-Reset:
              schema:
                type: string
                description: Seconds until the quota resets.
                example: '60'
              required: true
              description: Seconds until the quota resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying after a transient service outage.
                example: '5'
              required: true
              description: Seconds to wait before retrying after a transient service outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreditUsageDay:
      type: object
      properties:
        date:
          type: string
          description: Calendar day (`YYYY-MM-DD`) in the requested timezone.
          example: 2026-06-01
        usage:
          type: object
          additionalProperties:
            type: number
          description: Billable units consumed that day, keyed by billable operation. Operations with no usage are omitted.
      required:
      - date
      - usage
    CreditUsageLine:
      type: object
      properties:
        api:
          type: string
          description: The billable operation, e.g. `chat:completions` or `playbook:run`.
          example: chat:completions
        requests:
          type: number
          description: Total billable units consumed for this line over the range.
        unit:
          type: string
          nullable: true
          description: Display label for one billable unit (e.g. `request`). Null when pricing is unavailable.
        credits_per_unit:
          type: number
          nullable: true
          description: Credits charged per unit, from the current rate card. Null when pricing is unavailable.
        credits:
          type: number
          nullable: true
          description: Total credits for this line (`requests × credits_per_unit`). Null when pricing is unavailable.
      required:
      - api
      - requests
      - unit
      - credits_per_unit
      - credits
    ApiUsage:
      type: object
      properties:
        requests:
          type: number
          description: Total billable API requests across all operations.
        by_operation:
          type: object
          additionalProperties:
            type: number
          description: Billable API requests keyed by operation (e.g. `chat:completions`, `playbook:run`).
      required:
      - requests
      - by_operation
      description: API activity.
    WebUsage:
      type: object
      properties:
        messages:
          type: number
          description: Web-app chat messages sent.
        web_pages_scraped:
          type: number
          description: Web pages read by GC AI to compose answers.
        files_uploaded:
          type: number
          description: Files uploaded.
      required:
      - messages
      - web_pages_scraped
      - files_uploaded
      description: Web-app activity.
    WordUsage:
      type: object
      properties:
        messages:
          type: number
          description: Word add-in messages sent.
        redlines_applied:
          type: number
          description: Redlines applied from the Word add-in.
        drafts_applied:
          type: number
          description: Drafts applied from the Word add-in.
      required:
      - messages
      - redlines_applied
      - drafts_applied
      description: Word add-in activity.
    CreditUsageResponse:
      type: object
      properties:
        start_date:
          type: string
          description: Inclusive range start.
        end_date:
          type: string
          description: Inclusive range end.
        timezone:
          type: string
          description: IANA timezone used for day boundaries.
        pricing_available:
          type: boolean
          description: Whether rate-card pricing could be resolved for every observed operation. When false, all credit fields are null and only raw request counts are returned.
        total_credits:
          type: number
          nullable: true
          description: Total credits across all operations over the range. Null when pricing is unavailable.
        lines:
          type: array
          items:
            $ref: '#/components/schemas/CreditUsageLine'
          description: Per-operation usage and credit totals over the range.
        daily:
          type: array
          items:
            $ref: '#/components/schemas/CreditUsageDay'
          description: Daily usage buckets across the full range (days with no usage have an empty `usage` object).
      required:
      - start_date
      - end_date
      - timezone
      - pricing_available
      - total_credits
      - lines
      - daily
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Machine-readable error code present on some errors (e.g. `RATE_LIMITED`, `INSUFFICIENT_CREDITS`, `TRIAL_NOT_STARTED`, `BILLING_NOT_CONFIGURED`). Branch on this rather than the human-readable `error` string.
        message:
          type: string
          description: Additional error details
        details:
          type: object
          additionalProperties:
            nullable: true
          description: Validation error details (for 400 errors)
      required:
      - error
    UsageSummaryResponse:
      type: object
      properties:
        start_date:
          type: string
          description: Inclusive range start.
        end_date:
          type: string
          description: Inclusive range end.
        timezone:
          type: string
          description: IANA timezone used for day boundaries.
        web:
          $ref: '#/components/schemas/WebUsage'
        word:
          $ref: '#/components/schemas/WordUsage'
        api:
          $ref: '#/components/schemas/ApiUsage'
      required:
      - start_date
      - end_date
      - timezone
      - web
      - word
      - api
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key for authentication. Format: `gcai_xxxxxxxxx`


        Create API keys in the GC AI app under Settings → API.'