openapi: 3.2.0
info:
  title: Cloro Dev Countries API
  version: 1.0.0
  contact:
    name: cloro support
    email: support@cloro.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://cloro.dev/terms/
  description: 'Operations tagged Countries across 2 of this provider''s published API definitions: cloro-dev-openapi.json, cloro-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cloro.dev
  description: Production server
security:
- bearerAuth: []
tags:
- name: Countries
paths:
  /v1/countries:
    get:
      summary: List of countries
      description: Returns a list of all supported ISO 3166-1 alpha-2 country codes. Can be filtered by model to get countries available for specific AI providers.
      operationId: getCountries
      parameters:
      - name: model
        in: query
        description: Filter countries available for a specific model. Omit to return all supported countries.
        schema:
          type: string
          enum:
          - aimode
          - aioverview
          - chatgpt
          - copilot
          - gemini
          - google
          - grok
          - perplexity
        example: chatgpt
      responses:
        '200':
          description: List of supported country codes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - AF
                - AX
                - AL
                - DZ
                - AS
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
        '400':
          description: Bad Request - Invalid model parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found - Route not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too Many Requests - API key rate limit exceeded
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
      - Countries
    servers:
    - url: https://api.cloro.dev
      description: Production server
components:
  headers:
    XRateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 997
    XLatencyMs:
      description: Milliseconds the API spent on the request, from arrival to the start of the response. Excludes network transit.
      schema:
        type: integer
        example: 3420
    XRequestId:
      description: Unique ID for this request. Support uses it to find your request.
      schema:
        type: string
        format: uuid
        example: b0864943-5d45-4796-bc64-f052661256f0
    XRateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
        example: 1000
  schemas:
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Request validation failed
            details:
              type: array
              description: One entry per invalid field. Sent on request-body validation errors.
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: prompt
                  message:
                    type: string
                    example: Prompt cannot be empty
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    AuthenticationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - MISSING_API_KEY
              - INVALID_API_KEY_FORMAT
              - INVALID_OR_EXPIRED_API_KEY
              example: MISSING_API_KEY
            message:
              type: string
              example: Missing or invalid API key
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    InternalError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: INTERNAL_SERVER_ERROR
            message:
              type: string
              description: For example `Maximum retries exceeded` when every attempt failed, or `Internal server error` for an unexpected failure.
              example: Maximum retries exceeded
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    NotFoundError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: Route not found
            details:
              type: object
              properties:
                id:
                  type: string
                  example: /v1/invalid-endpoint
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    RateLimitError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: API key rate limit exceeded
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: cloro API key as a bearer token. One key grants every endpoint in this spec; per-key scopes are not available, so a client cannot request a narrower permission. Keys are created and revoked in the [dashboard](https://dashboard.cloro.dev/api-keys).
x-refined-from:
- cloro-dev-openapi.json
- cloro-dev-openapi.yml