Hamad Bin Khalifa University Moderations API

openapi: 3.2.0
info:
  title: Fanar Moderations API
  description: 'You can interact with FanarAPI for seamless chat completion and text processing using Fanar.

    Base URL: https://api.fanar.qa

    Request API Access: https://api.fanar.qa/request

    Models and release history: https://fanar.qa/en/models

    Rate Limits


    To ensure fair usage and optimal performance for all users, our API has rate limits in place. When you exceed a rate limit, your request will typically receive a 429 Too Many Requests HTTP status code.


    Limits by model


    These are our default settings for all models. We understand that your needs may vary. If your application requires higher throughput or more tailored rate limits for specific models, please contact us:


    Model

    Rate Limit


    Fanar

    50 requests/minute


    Fanar-S-1-7B

    50 requests/minute


    Fanar-C-1-8.7B

    50 requests/minute


    Fanar-C-2-27B

    50 requests/minute


    Fanar-2.0-Tools

    50 requests/minute


    Fanar-Sadiq

    50 requests/minute


    Fanar-Sadiq-2

    50 requests/minute


    Fanar-Sadiq-2 (validate)

    200 requests/minute


    Fanar-Sadiq-2 (deep research)

    20 requests/day


    Fanar-Sadiq-TTS-1

    20 requests/day


    Fanar-Oryx-IVU-2

    20 requests/day


    Fanar-Aura-TTS-2

    20 requests/day


    Fanar-Aura-STT-1

    20 requests/day


    Fanar-Aura-STT-LF-1

    10 requests/day


    Fanar-3.0-Aura-Transcribe (live stream sessions)

    20 requests/day


    Fanar-Oryx-IG-2

    20 requests/day


    Fanar-Guard-2

    50 requests/minute


    Fanar-Shaheen-MT-1

    20 requests/day


    Fanar-3.0-Shaheen-Translate

    20 requests/day


    Fanar-Diwan

    50 requests/minute


    Response headers


    Every rate-limited response reports your current quota, so you can back off before being throttled:


    Header

    Description


    x-ratelimit-limitRequests allowed per window.


    x-ratelimit-remainingRequests still available in the current window.


    x-ratelimit-resetSeconds until a request slot frees up.


    ratelimit-policyThe quota and its window in seconds, as limit;w=seconds — so 100;w=86400 means 100 requests per day.


    retry-afterSeconds to wait before retrying, sent only on a 429. When your own quota ran out it counts down to a free slot; when an upstream service throttled the request it carries that service''s own hint instead.


    Because x-ratelimit-limit alone cannot tell 3 per minute from 3 per day, read ratelimit-policy when you need the window. These headers are omitted for API keys with unlimited quota.'
  termsOfService: https://api.fanar.qa/terms-of-service
  contact:
    name: Fanar Support
    url: https://fanar.qa/
    email: support@fanar.qa
  version: 1.0.0
  x-logo:
    url: /static/white-logo.svg
    alt: logo
security:
- Bearer: []
tags:
- name: Moderations
paths:
  /v1/moderations:
    post:
      tags:
      - Moderations
      summary: Identify Safety
      description: 'FanarGuard gives each prompt–response pair safety and cultural-awareness scores, allowing moderation thresholds to be tailored to the deployment.

        For our definition of cultural awareness, refer to https://arxiv.org/abs/2511.18852.'
      operationId: identify_safety_v1_moderations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SafetyFilterRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SafetyFilterResponse'
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: invalid_authentication
                  message: Invalid authentication
                  status: 401
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: invalid_authorization
                  message: Invalid authorization
                  status: 403
        '429':
          description: Rate limit reached or Exceeded quota
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: exceeded_quota
                  message: Exceeded quota
                  status: 429
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: internal_server_error
                  message: Internal server error
                  status: 500
        '503':
          description: Service overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: overloaded
                  message: Service overloaded
                  status: 503
        '504':
          description: Request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: timeout
                  message: Request timed out
                  status: 504
        '413':
          description: Request entity too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: too_large
                  message: Request entity too large
                  status: 413
        '422':
          description: Unprocessable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unprocessable
                  message: Unprocessable
                  status: 422
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: conflict
                  message: Conflict
                  status: 409
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: Not found
                  message: Not found
                  status: 404
        '410':
          description: No longer supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: no_longer_supported
                  message: No longer supported
                  status: 410
        '499':
          description: Client closed request before completion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: client_closed_request
                  message: Client closed request before completion
                  status: 499
      security:
      - Bearer: []
      x-codeSamples:
      - lang: Curl
        label: cURL
        source: "curl -X POST \"https://api.fanar.qa/v1/moderations\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -d '{\n    \"model\": \"Fanar-Guard-2\",\n    \"prompt\": \"Your prompt here\",\n    \"response\": \"Response from the model here\"\n  }'\n"
      - lang: Python
        label: Python - requests
        source: "import requests\n\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\",\n}\n\njson_data = {\n    \"model\": \"Fanar-Guard-2\",\n    \"prompt\": \"Your prompt here\",\n    \"response\": \"Response from the model here\",\n}\n\nresponse = requests.post(\"https://api.fanar.qa/v1/moderations\", headers=headers, json=json_data)\n\nprint(response.json())  # Print the safety and cultural awareness scores"
components:
  schemas:
    ErrorStatus:
      type: integer
      enum:
      - 400
      - 401
      - 403
      - 429
      - 429
      - 500
      - 503
      - 504
      - 413
      - 422
      - 409
      - 404
      - 410
      - 499
      title: ErrorStatus
    ErrorContentFilterType:
      type: string
      enum:
      - safety
      - blocklist
      - incomplete
      title: ErrorContentFilterType
    ModerationModels:
      type: string
      enum:
      - Fanar-Guard-2
      title: ModerationModels
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          title: Message
          default: Internal server error
        status:
          $ref: '#/components/schemas/ErrorStatus'
          default: 500
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
        type:
          anyOf:
          - $ref: '#/components/schemas/ErrorContentFilterType'
          - type: 'null'
      type: object
      title: Error
    ErrorCode:
      type: string
      enum:
      - content_filter
      - invalid_authentication
      - invalid_authorization
      - rate_limit_reached
      - exceeded_quota
      - internal_server_error
      - overloaded
      - timeout
      - too_large
      - unprocessable
      - conflict
      - Not found
      - no_longer_supported
      - client_closed_request
      title: ErrorCode
    SafetyFilterRequest:
      properties:
        model:
          $ref: '#/components/schemas/ModerationModels'
          description: The model to use for safety filtering.
        prompt:
          type: string
          title: Prompt
          description: The prompt.
        response:
          type: string
          title: Response
          description: The model's response to the prompt.
      type: object
      required:
      - model
      - prompt
      - response
      title: SafetyFilterRequest
      example:
        model: Fanar-Guard-2
        prompt: What is the weather?
        response: The weather is sunny today.
    SafetyFilterResponse:
      properties:
        safety:
          type: number
          title: Safety
          description: The safety score for general safety aspects such as toxicity, violence, self-harm, etc.
        cultural_awareness:
          type: number
          title: Cultural Awareness
          description: The cultural awareness score for aspects such as stereotypes, insensitive content, and bias.
      type: object
      required:
      - safety
      - cultural_awareness
      title: SafetyFilterResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Provide your API key in the Authorization header using the Bearer scheme.