openapi: 3.0.3
info:
  title: Stigg API
  description: >-
    Stigg is a pricing and packaging platform providing feature management,
    entitlements, and usage-based billing for SaaS and API products. The Stigg API
    exposes GraphQL and REST endpoints for customer provisioning, subscription
    management, entitlement checking, and usage reporting. Authentication requires
    a Full access key passed via the X-API-KEY header.
  version: '1.0'
  contact:
    url: https://www.stigg.io/
  termsOfService: https://www.stigg.io/terms
servers:
  - url: https://api.stigg.io
    description: Stigg Production API
tags:
  - name: Customers
    description: Customer provisioning and management.
  - name: Subscriptions
    description: Subscription lifecycle management.
  - name: Entitlements
    description: Feature access and entitlement checks.
  - name: Usage
    description: Usage reporting and metering.
paths:
  /graphql:
    post:
      operationId: executeGraphQL
      summary: Execute GraphQL Query or Mutation
      description: >-
        Execute any Stigg GraphQL query or mutation. Stigg uses GraphQL as its
        primary API. Send a JSON body with a query/mutation string and optional
        variables. Supports customer management, subscription operations,
        entitlement checks, and usage reporting.
      tags:
        - Customers
        - Subscriptions
        - Entitlements
        - Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              provisionCustomer:
                summary: Provision a Customer
                value:
                  query: |
                    mutation ProvisionCustomer($input: ProvisionCustomerInput!) {
                      provisionCustomer(input: $input) {
                        customer { id name email }
                        subscription { id status plan { id name } }
                      }
                    }
                  variables:
                    input:
                      customerId: "customer-123"
                      name: "Acme Corp"
                      email: "admin@acme.com"
              checkEntitlement:
                summary: Check Feature Entitlement
                value:
                  query: |
                    query GetCustomerEntitlement($customerId: String!, $featureId: String!) {
                      customerEntitlement(customerId: $customerId, featureId: $featureId) {
                        isGranted
                        usageLimit
                        currentUsage
                        resetPeriod
                      }
                    }
                  variables:
                    customerId: "customer-123"
                    featureId: "feature-api-calls"
              reportUsage:
                summary: Report Feature Usage
                value:
                  query: |
                    mutation ReportUsage($input: ReportUsageInput!) {
                      reportUsage(input: $input) { id }
                    }
                  variables:
                    input:
                      customerId: "customer-123"
                      featureId: "feature-api-calls"
                      value: 100
      responses:
        '200':
          description: GraphQL response (may contain data or errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Invalid or missing X-API-KEY header.
components:
  schemas:
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: GraphQL query or mutation string.
        variables:
          type: object
          description: Variables for the GraphQL operation.
          additionalProperties: true
        operationName:
          type: string
          description: Named operation to execute when the document contains multiple.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          description: Response data from the GraphQL operation.
          additionalProperties: true
        errors:
          type: array
          description: Array of GraphQL errors if any occurred.
          items:
            $ref: '#/components/schemas/GraphQLError'
    GraphQLError:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        locations:
          type: array
          items:
            type: object
            properties:
              line:
                type: integer
              column:
                type: integer
        path:
          type: array
          items:
            type: string
        extensions:
          type: object
          additionalProperties: true
    Customer:
      type: object
      description: A Stigg customer representing a tenant or end-user organization.
      properties:
        id:
          type: string
          description: Unique customer identifier.
        name:
          type: string
          description: Customer display name.
        email:
          type: string
          format: email
          description: Customer email address.
        createdAt:
          type: string
          format: date-time
          description: Customer creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: Customer last updated timestamp.
    Subscription:
      type: object
      description: A Stigg subscription linking a customer to a pricing plan.
      properties:
        id:
          type: string
          description: Unique subscription identifier.
        status:
          type: string
          enum: [ACTIVE, CANCELED, TRIAL, PAUSED]
          description: Subscription status.
        plan:
          $ref: '#/components/schemas/Plan'
        startDate:
          type: string
          format: date-time
          description: Subscription start date.
        endDate:
          type: string
          format: date-time
          description: Subscription end date (if applicable).
    Plan:
      type: object
      description: A Stigg pricing plan.
      properties:
        id:
          type: string
          description: Plan identifier.
        name:
          type: string
          description: Plan display name.
        description:
          type: string
          description: Plan description.
    Entitlement:
      type: object
      description: A customer's access right to a specific feature.
      properties:
        featureId:
          type: string
          description: Feature identifier.
        isGranted:
          type: boolean
          description: Whether access to the feature is granted.
        usageLimit:
          type: integer
          description: Maximum allowed usage (null for unlimited).
        currentUsage:
          type: integer
          description: Current usage within the reset period.
        resetPeriod:
          type: string
          description: Period when usage resets (e.g., MONTHLY, WEEKLY).
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Full access key from the Stigg dashboard (Integrations > API keys).
security:
  - ApiKey: []