openapi: 3.0.3
info:
  title: ReqRes Agent Sandbox API
  description: 'OpenAPI specification for the ReqRes API. Covers legacy demo endpoints, collections, app-user auth flows, custom endpoints, and the Agent Sandbox (/agent/v1/*) for AI coding agents. All /api/* endpoints require x-api-key. All /app/* endpoints require Authorization: Bearer <session_token>. /agent/v1/* endpoints are open in v1 (IP-based rate limiting).'
  version: 2.1.0
  contact:
    name: ReqRes Support
    url: https://reqres.in
    email: hello@reqres.in
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
  x-source-url: https://reqres.in/openapi.json
servers:
- url: https://reqres.in
  description: Production server
- url: http://localhost:8000
  description: Development server
tags:
- name: Agent Sandbox
  description: Endpoints designed for AI coding agents. Cursor pagination, deeply nested resources, deliberate error scenarios, deterministic seeded fixtures.
paths:
  /agent/v1/health:
    get:
      summary: ReqRes Agent Sandbox Health Probe
      description: Lightweight health check that returns sandbox status, version, uptime, and the caller's current rate-limit status. Cached at the edge for 10 seconds. Cheap to poll. Send the optional x-agent-id header to elevate to Agent Developer tier limits.
      operationId: agentHealth
      tags:
      - Agent Sandbox
      responses:
        '200':
          description: Healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentHealthResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agent/v1/users:
    get:
      summary: ReqRes List Agent Users (cursor Pagination)
      description: 'Paginated user list with realistic edge cases: nullable nested fields, sparse fieldsets, silent param clamping. Use meta.next_cursor for next page; never increment a page number.'
      operationId: agentListUsers
      tags:
      - Agent Sandbox
      parameters:
      - name: cursor
        in: query
        schema:
          type: string
        description: Opaque cursor from previous response. Omit for first page.
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Page size (silently clamped at 100).
      - name: fields
        in: query
        schema:
          type: string
        description: Comma-separated sparse fieldset (e.g. id,email,full_name).
      - name: seed
        in: query
        schema:
          type: integer
          default: 42
        description: Deterministic fixture seed.
      responses:
        '200':
          description: Paginated user list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentUserListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agent/v1/users/{id}:
    get:
      summary: ReqRes Get a Single Agent User with Optional Expansion
      description: Returns one user. Without ?expand=, nested resources (addresses, activity, organizations) are returned as references. With ?expand=addresses,activity, those resources are inlined.
      operationId: agentGetUser
      tags:
      - Agent Sandbox
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^usr_[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$
        description: ULID with usr_ prefix.
      - name: expand
        in: query
        schema:
          type: string
        description: 'Comma-separated: addresses, activity, organizations.'
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentUserDetailResponse'
        '400':
          description: Invalid ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agent/v1/auth/login:
    post:
      summary: ReqRes Agent Auth Login (with MFA Branch)
      description: Returns a session for normal accounts or an MFA challenge for accounts with email matching '+mfa@'. Use '+wrong@' or '+locked@' suffixes to trigger 401 branches.
      operationId: agentLogin
      tags:
      - Agent Sandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
      responses:
        '200':
          description: Session created or MFA challenge
          content:
            application/json: {}
        '400':
          description: Missing fields
        '401':
          description: Invalid credentials or account locked
        '422':
          description: Validation error
        '429':
          description: Rate limited
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agent/v1/orders:
    get:
      summary: ReqRes List Agent Orders (relational Data)
      description: Orders with relational references (customer, line items, products, addresses). Money is always {amount, currency, formatted}. Some line_items reference deleted products.
      operationId: agentListOrders
      tags:
      - Agent Sandbox
      parameters:
      - name: cursor
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - paid
          - shipped
          - delivered
          - refunded
          - cancelled
      - name: seed
        in: query
        schema:
          type: integer
          default: 42
      responses:
        '200':
          description: Paginated order list
          content:
            application/json: {}
        '400':
          description: Invalid status filter
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agent/v1/scenarios:
    get:
      summary: ReqRes List Training Scenarios
      description: Returns the catalogue of available failure scenarios.
      operationId: agentListScenarios
      tags:
      - Agent Sandbox
      responses:
        '200':
          description: Scenario list
          content:
            application/json: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agent/v1/scenarios/{scenario}:
    get:
      summary: ReqRes Trigger a Deliberate Failure Scenario
      description: 'Returns a controlled failure for testing agent error handling. All responses include header X-Agent-Sandbox-Intentional: <scenario> so error reporters can suppress them. Available scenarios: rate-limited, server-error, bad-gateway, timeout, validation-error, unauthorized, forbidden, not-found, conflict, too-large, slow, partial-content, redirect-loop, malformed-json, empty-response.'
      operationId: agentScenario
      tags:
      - Agent Sandbox
      parameters:
      - name: scenario
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Slow / partial-content / empty-response / malformed-json scenarios
        '206':
          description: Partial content
        '302':
          description: Redirect loop hop
        '401':
          description: Unauthorized scenario
        '403':
          description: Forbidden scenario
        '404':
          description: Not-found scenario or unknown scenario name
        '409':
          description: Conflict scenario
        '413':
          description: Too-large scenario
        '422':
          description: Validation-error scenario
        '429':
          description: Rate-limited scenario
        '500':
          description: Server-error scenario
        '502':
          description: Bad-gateway scenario
        '504':
          description: Timeout scenario (returns immediately, see X-Agent-Sandbox-Simulated-Delay header)
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AgentHealthResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - status
          - version
          - uptime_seconds
          - rate_limit_status
          - deprecations
          properties:
            status:
              type: string
              enum:
              - healthy
              - degraded
              - maintenance
            version:
              type: string
            uptime_seconds:
              type: integer
            rate_limit_status:
              type: object
              properties:
                tier:
                  type: string
                remaining_today:
                  type:
                  - integer
                  - 'null'
                limit_today:
                  type:
                  - integer
                  - 'null'
                reset_at:
                  type:
                  - string
                  - 'null'
                  format: date-time
            deprecations:
              type: array
              items:
                type: object
    AgentPaginationMeta:
      type: object
      required:
      - limit
      - returned
      - next_cursor
      - prev_cursor
      - has_more
      - total_estimate
      properties:
        limit:
          type: integer
        returned:
          type: integer
        next_cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor or null if at end.
        prev_cursor:
          type:
          - string
          - 'null'
          description: Always null in v1 (forward-only pagination).
        has_more:
          type: boolean
        total_estimate:
          type: integer
    AgentUser:
      type: object
      required:
      - id
      - email
      - full_name
      - locale
      - created_at
      - updated_at
      - timezone
      - profile
      - preferences
      - status
      properties:
        id:
          type: string
          pattern: ^usr_[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$
        email:
          type: string
          format: email
        full_name:
          type: string
        locale:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        timezone:
          type: string
        profile:
          type: object
          properties:
            avatar_url:
              type:
              - string
              - 'null'
            bio:
              type:
              - string
              - 'null'
            company:
              type:
              - object
              - 'null'
              properties:
                name:
                  type: string
                department:
                  type: string
                employee_id:
                  type: string
            social:
              type: object
              properties:
                twitter:
                  type:
                  - string
                  - 'null'
                github:
                  type:
                  - string
                  - 'null'
                linkedin:
                  type:
                  - string
                  - 'null'
        preferences:
          type: object
        status:
          type: string
          enum:
          - active
          - suspended
    AgentUserListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentUser'
        meta:
          $ref: '#/components/schemas/AgentPaginationMeta'
    AgentUserDetailResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/AgentUser'
    AgentErrorResponse:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable message.
        hint:
          type: string
        request_id:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: session_token