openapi: 3.1.0
info:
  title: DreamFactory System Admin Limit API
  description: The DreamFactory System API provides administrative management capabilities for DreamFactory instances. It allows administrators to manage services, apps, roles, users, CORS configurations, email templates, environment settings, lookups, events, scripts, and more. All system resources are accessible under the /api/v2/system/ base path. Authentication requires either an X-DreamFactory-Session-Token header (for system admins) or an X-DreamFactory-API-Key header (for users with appropriate permissions).
  version: 2.0.0
  contact:
    name: DreamFactory Support
    url: https://www.dreamfactory.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://www.dreamfactory.com/terms-of-use
servers:
- url: https://{instance}/api/v2
  description: DreamFactory instance
  variables:
    instance:
      default: example.dreamfactory.com
      description: Your DreamFactory instance hostname
security:
- sessionToken: []
- apiKey: []
tags:
- name: Limit
  description: API rate limiting management
paths:
  /system/limit:
    get:
      operationId: listLimits
      summary: DreamFactory List API limits
      description: Retrieve a list of API rate limits.
      tags:
      - Limit
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createLimit
      summary: DreamFactory Create API limit
      description: Create a new API rate limit.
      tags:
      - Limit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LimitRequest'
      responses:
        '201':
          description: Limit created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /system/limit/{id}:
    get:
      operationId: getLimit
      summary: DreamFactory Get API limit
      description: Retrieve a specific API limit by ID.
      tags:
      - Limit
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      operationId: updateLimit
      summary: DreamFactory Update API limit
      description: Update a specific API limit by ID.
      tags:
      - Limit
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LimitRequest'
      responses:
        '200':
          description: Limit updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteLimit
      summary: DreamFactory Delete API limit
      description: Delete a specific API limit by ID.
      tags:
      - Limit
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Limit deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /system/limit_cache:
    get:
      operationId: listLimitCache
      summary: DreamFactory List limit cache
      description: Retrieve current limit volume levels to check how close limits are to being reached.
      tags:
      - Limit
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: resetLimitCache
      summary: DreamFactory Reset limit counters
      description: Reset limit counters manually.
      tags:
      - Limit
      responses:
        '200':
          description: Limit cache reset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    LimitListResponse:
      type: object
      properties:
        resource:
          type: array
          items:
            $ref: '#/components/schemas/LimitResponse'
    LimitResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        type:
          type: string
        rate:
          type: integer
        period:
          type: string
        service_id:
          type: integer
        role_id:
          type: integer
        user_id:
          type: integer
        is_active:
          type: boolean
        created_date:
          type: string
          format: date-time
        last_modified_date:
          type: string
          format: date-time
    ResourceListResponse:
      type: object
      properties:
        resource:
          type: array
          items:
            type: object
    LimitRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the limit.
        description:
          type: string
          description: Description of the limit.
        type:
          type: string
          description: Type of limit (instance, each_user, each_service, etc.).
        rate:
          type: integer
          description: Number of allowed API calls in the period.
        period:
          type: string
          description: Time period for the limit (minute, hour, day, etc.).
        service_id:
          type: integer
          description: Service ID the limit applies to.
        role_id:
          type: integer
          description: Role ID the limit applies to.
        user_id:
          type: integer
          description: User ID the limit applies to.
        is_active:
          type: boolean
          description: Whether the limit is active.
      required:
      - name
      - type
      - rate
      - period
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: Error code.
            message:
              type: string
              description: Error message.
            context:
              type: object
              description: Additional error context.
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
  parameters:
    id:
      name: id
      in: path
      required: true
      description: Resource identifier.
      schema:
        type: integer
    limit:
      name: limit
      in: query
      description: Maximum number of records to return.
      schema:
        type: integer
        default: 0
    filter:
      name: filter
      in: query
      description: SQL-like filter to limit results.
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: Comma-delimited list of fields to return.
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: Number of records to skip for pagination.
      schema:
        type: integer
        default: 0
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing session token or API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    sessionToken:
      type: apiKey
      name: X-DreamFactory-Session-Token
      in: header
      description: Session token obtained after admin login.
    apiKey:
      type: apiKey
      name: X-DreamFactory-API-Key
      in: header
      description: API key associated with a registered application.
externalDocs:
  description: DreamFactory Documentation
  url: https://guide.dreamfactory.com/docs/