openapi: 3.2.0
info:
  title: Cloro Dev States 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 States 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: States
paths:
  /v1/states:
    get:
      summary: List of states
      description: Returns a list of US states supported for state-level geo-targeting. Only US is currently supported — other country values return an empty array.
      operationId: getStates
      parameters:
      - name: country
        in: query
        required: true
        description: ISO 3166-1 alpha-2 country code. Only "US" returns results.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
        example: US
      responses:
        '200':
          description: List of supported states
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: USPS two-letter state code
                      example: CA
                    name:
                      type: string
                      description: Full state name
                      example: California
                  required:
                  - code
                  - name
                example:
                - code: AL
                  name: Alabama
                - code: AK
                  name: Alaska
                - code: AZ
                  name: Arizona
                - code: CA
                  name: California
                - code: DC
                  name: District of Columbia
                - code: NY
                  name: New York
                - code: TX
                  name: Texas
          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 — missing or invalid country parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '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:
      - States
    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'
    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