openapi: 3.1.0
info:
  title: Stack Exchange Answers Users API
  description: The Stack Exchange API v2.3 provides programmatic access to the Stack Exchange network of Q&A sites, including Stack Overflow, Server Fault, Super User, and hundreds of other communities. The API supports reading and writing questions, answers, comments, tags, users, and other content. Authentication is via OAuth 2.0 with access tokens. All responses are JSON-encoded and support GZIP compression.
  version: '2.3'
  contact:
    name: Stack Exchange API Support
    url: http://stackapps.com/
    email: team+api@stackexchange.com
  termsOfService: https://stackexchange.com/legal/api-terms-of-use
servers:
- url: https://api.stackexchange.com/2.3
  description: Stack Exchange API v2.3
security:
- oauth2: []
- {}
tags:
- name: Users
  description: Operations for retrieving user profiles, activity, and reputation on Stack Exchange sites.
paths:
  /users:
    get:
      operationId: getUsers
      summary: Get All Users
      description: Returns all users on a Stack Exchange site. Results can be filtered by inname to match users whose display name contains the given string.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/site'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pagesize'
      - $ref: '#/components/parameters/fromdate'
      - $ref: '#/components/parameters/todate'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/sort'
      - name: inname
        in: query
        schema:
          type: string
        description: Filter users whose display name contains this string
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
  /users/{ids}:
    get:
      operationId: getUsersByIds
      summary: Get Users by IDs
      description: Returns the users identified by a semicolon-delimited list of user IDs.
      tags:
      - Users
      parameters:
      - name: ids
        in: path
        required: true
        schema:
          type: string
        description: Semicolon-delimited list of user IDs
      - $ref: '#/components/parameters/site'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: Users matching the provided IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
  /users/{ids}/questions:
    get:
      operationId: getQuestionsByUser
      summary: Get Questions by User
      description: Returns the questions asked by the users identified in the IDs parameter.
      tags:
      - Users
      parameters:
      - name: ids
        in: path
        required: true
        schema:
          type: string
        description: Semicolon-delimited list of user IDs
      - $ref: '#/components/parameters/site'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pagesize'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: Questions asked by the specified users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionsResponse'
  /users/{ids}/answers:
    get:
      operationId: getAnswersByUser
      summary: Get Answers by User
      description: Returns the answers posted by the users identified in the IDs parameter.
      tags:
      - Users
      parameters:
      - name: ids
        in: path
        required: true
        schema:
          type: string
        description: Semicolon-delimited list of user IDs
      - $ref: '#/components/parameters/site'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pagesize'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: Answers posted by the specified users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswersResponse'
  /users/me:
    get:
      operationId: getAuthenticatedUser
      summary: Get Authenticated User
      description: Returns the authenticated user associated with the provided access token. Requires authentication.
      tags:
      - Users
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/site'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: The authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Question:
      type: object
      description: A question on a Stack Exchange site
      properties:
        question_id:
          type: integer
          description: Unique identifier of the question
        title:
          type: string
          description: The title of the question
        body:
          type: string
          description: The HTML body of the question
        body_markdown:
          type: string
          description: The Markdown body of the question
        score:
          type: integer
          description: The net vote score of the question
        view_count:
          type: integer
          description: Number of times the question has been viewed
        answer_count:
          type: integer
          description: Number of answers the question has received
        accepted_answer_id:
          type: integer
          description: ID of the accepted answer if one exists
        is_answered:
          type: boolean
          description: Whether the question has an accepted answer
        creation_date:
          type: integer
          description: Unix timestamp of when the question was created
        last_activity_date:
          type: integer
          description: Unix timestamp of the last activity on the question
        last_edit_date:
          type: integer
          description: Unix timestamp of the last edit
        owner:
          $ref: '#/components/schemas/ShallowUser'
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the question
        link:
          type: string
          format: uri
          description: Link to the question page
        closed_reason:
          type: string
          description: Reason the question was closed if applicable
        closed_date:
          type: integer
          description: Unix timestamp of when the question was closed
        bounty_amount:
          type: integer
          description: Bounty amount if an active bounty exists
        bounty_closes_date:
          type: integer
          description: Unix timestamp when the bounty closes
    Answer:
      type: object
      description: An answer to a question on a Stack Exchange site
      properties:
        answer_id:
          type: integer
          description: Unique identifier of the answer
        question_id:
          type: integer
          description: ID of the question this answer belongs to
        body:
          type: string
          description: The HTML body of the answer
        body_markdown:
          type: string
          description: The Markdown body of the answer
        score:
          type: integer
          description: The net vote score of the answer
        is_accepted:
          type: boolean
          description: Whether this answer has been accepted by the question owner
        creation_date:
          type: integer
          description: Unix timestamp of when the answer was created
        last_activity_date:
          type: integer
          description: Unix timestamp of the last activity on the answer
        last_edit_date:
          type: integer
          description: Unix timestamp of the last edit
        owner:
          $ref: '#/components/schemas/ShallowUser'
        link:
          type: string
          format: uri
          description: Link to the answer on the question page
    QuestionsResponse:
      allOf:
      - $ref: '#/components/schemas/Wrapper'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/Question'
    ErrorResponse:
      type: object
      properties:
        error_id:
          type: integer
          description: Numeric error identifier
        error_message:
          type: string
          description: Human-readable error description
        error_name:
          type: string
          description: Machine-readable error name
    AnswersResponse:
      allOf:
      - $ref: '#/components/schemas/Wrapper'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/Answer'
    User:
      type: object
      description: A user profile on a Stack Exchange site
      properties:
        user_id:
          type: integer
          description: Unique identifier of the user
        display_name:
          type: string
          description: The user's display name
        reputation:
          type: integer
          description: The user's reputation score
        user_type:
          type: string
          description: The type of user account
        profile_image:
          type: string
          format: uri
          description: URL of the user's profile image
        website_url:
          type: string
          format: uri
          description: URL of the user's personal website
        location:
          type: string
          description: The user's self-reported location
        about_me:
          type: string
          description: HTML text of the user's about me section
        creation_date:
          type: integer
          description: Unix timestamp of when the account was created
        last_access_date:
          type: integer
          description: Unix timestamp of the user's last access
        last_modified_date:
          type: integer
          description: Unix timestamp of the last modification
        question_count:
          type: integer
          description: Number of questions asked
        answer_count:
          type: integer
          description: Number of answers posted
        up_vote_count:
          type: integer
          description: Number of upvotes cast
        down_vote_count:
          type: integer
          description: Number of downvotes cast
        link:
          type: string
          format: uri
          description: Link to the user's profile page
        accept_rate:
          type: integer
          description: Percentage of questions the user has accepted answers for
    ShallowUser:
      type: object
      description: A shallow representation of a Stack Exchange user
      properties:
        user_id:
          type: integer
          description: Unique identifier of the user
        display_name:
          type: string
          description: The user's display name
        reputation:
          type: integer
          description: The user's reputation score
        user_type:
          type: string
          enum:
          - unregistered
          - registered
          - moderator
          - named_moderator
          - team_admin
          description: The type of user account
        profile_image:
          type: string
          format: uri
          description: URL of the user's profile image
        link:
          type: string
          format: uri
          description: Link to the user's profile page
        accept_rate:
          type: integer
          description: Percentage of questions the user has accepted answers for
    Wrapper:
      type: object
      description: Standard Stack Exchange API response wrapper containing items, pagination info, and backoff/quota information.
      properties:
        items:
          type: array
          description: The list of items returned
          items:
            type: object
        has_more:
          type: boolean
          description: Whether there are more results available
        quota_max:
          type: integer
          description: Maximum number of requests allowed per day
        quota_remaining:
          type: integer
          description: Number of requests remaining for today
        backoff:
          type: integer
          description: Number of seconds to wait before making additional requests if the API has asked for backoff
        total:
          type: integer
          description: Total number of items available
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        type:
          type: string
          description: The type of items in the response
        error_id:
          type: integer
          description: Error identifier if an error occurred
        error_message:
          type: string
          description: Human-readable error description
        error_name:
          type: string
          description: Machine-readable error name
    UsersResponse:
      allOf:
      - $ref: '#/components/schemas/Wrapper'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/User'
  parameters:
    order:
      name: order
      in: query
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
      description: Sort order for results
    site:
      name: site
      in: query
      required: true
      schema:
        type: string
        default: stackoverflow
      description: The Stack Exchange site to query. Use the API name of the site, e.g., stackoverflow, serverfault, superuser.
      example: stackoverflow
    todate:
      name: todate
      in: query
      schema:
        type: integer
      description: Unix timestamp for the maximum creation date
    fromdate:
      name: fromdate
      in: query
      schema:
        type: integer
      description: Unix timestamp for the minimum creation date
    filter:
      name: filter
      in: query
      schema:
        type: string
      description: A filter to control which fields are returned in the response. Use the /filter endpoint to create custom filters.
    page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: The page number to return (1-indexed)
    pagesize:
      name: pagesize
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 100
        default: 30
      description: Number of results to return per page (max 100)
    sort:
      name: sort
      in: query
      schema:
        type: string
      description: The field to sort results by (varies by endpoint)
  responses:
    Unauthorized:
      description: Authentication required or token is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for Stack Exchange API. Register an application at http://stackapps.com/apps/oauth to obtain client credentials.
      flows:
        authorizationCode:
          authorizationUrl: https://stackoverflow.com/oauth
          tokenUrl: https://stackoverflow.com/oauth/access_token/json
          scopes:
            no_expiry: Issues an access token that does not expire
            write_access: Allows write access to a user's data
            private_info: Access a user's private information
externalDocs:
  description: Stack Exchange API Documentation
  url: https://api.stackexchange.com/docs