iNaturalist Users API

swagger: '2.0'
info:
  title: iNaturalist Annotations Users API
  description: '# https://api.inaturalist.org/v1/


    [iNaturalist](https://www.inaturalist.org/) is a global community of

    naturalists, scientists, and members of the public sharing over a million

    wildlife sightings to teach one another about the natural world while

    creating high quality citizen science data for science and conservation.


    These API methods return data in JSON/JSONP and PNG response formats. They

    are meant to supplement the existing [iNaturalist

    API](https://www.inaturalist.org/pages/api+reference), implemented in Ruby

    on Rails, which has more functionality and supports more write operations,

    but tends to be slower and have less consistent response formats. Visit our

    [developers page](https://www.inaturalist.org/pages/developers) for more

    information. Write operations that expect and return JSON describe a single

    `body` parameter that represents the request body, which should be specified

    as JSON. See the "Model" of each body parameter for attributes that we

    accept in these JSON objects.


    Multiple values for a single URL parameter should be separated by commas,

    e.g. `taxon_id=1,2,3`.


    Map tiles are generated using the

    [node-mapnik](https://github.com/mapnik/node-mapnik) library, following the

    XYZ map tiling scheme. The "Observation Tile" methods accept nearly all the

    parameters of the observation search APIs, and will generate map tiles

    reflecting the same observations returned by searches. These

    "Observation Tile" methods have corresponding

    [UTFGrid](https://github.com/mapbox/utfgrid-spec) JSON

    responses which return information needed to make interactive maps.


    Authentication in the Node API is handled via JSON Web Tokens (JWT). To

    obtain one, make an [OAuth-authenticated

    request](http://www.inaturalist.org/pages/api+reference#auth) to

    https://www.inaturalist.org/users/api_token. Each JWT will expire after 24

    hours. Authentication required for all PUT and POST requests. Some GET

    requests will also include private information like hidden coordinates if

    the authenticated user has permission to view them.


    Photos served from https://static.inaturalist.org and

    https://inaturalist-open-data.s3.amazonaws.com have multiple size

    variants and not all size variants are returned in responses. To access

    other sizes, the photo URL can be modified to replace only the size

    qualifier (each variant shares the exact same extension). The domain a photo

    is hosted under reflects the license under which the photo is being shared,

    and the domain may change over time if the license changes. Photos in

    the `inaturalist-open-data` domain are shared under open licenses. These can

    be accessed in bulk in the [iNaturalist AWS Open Dataset](

    https://registry.opendata.aws/inaturalist-open-data/). Photos in the

    `static.inaturalist.org` domain do not have open licenses.


    The available photo sizes are:

    * original (max 2048px in either dimension)

    * large (max 1024px in either dimension)

    * medium (max 500px in either dimension)

    * small (max 240px in either dimension)

    * thumb (max 100px in either dimension)

    * square (75px square)


    iNaturalist Website: https://www.inaturalist.org/


    Open Source Software: https://github.com/inaturalist/


    ## Terms of Use


    Use of this API is subject to the iNaturalist

    [Terms of Service](https://www.inaturalist.org/terms) and

    [Privacy Policy](https://www.inaturalist.org/privacy). We will block any

    use of our API that violates our Terms or Privacy Policy without notice.

    The API is intended to support application development, not data scraping.

    For pre- generated data exports, see

    https://www.inaturalist.org/pages/developers.


    Please note that we throttle API usage to a max of 100 requests per minute,

    though we ask that you try to keep it to 60 requests per minute or lower,

    and to keep under 10,000 requests per day. If we notice usage that has

    serious impact on our performance we may institute blocks without

    notification.


    Terms of Service: https://www.inaturalist.org/terms


    Privacy Policy: https://www.inaturalist.org/privacy

    '
  version: 1.3.0
basePath: /v1
schemes:
- http
- https
produces:
- application/json
tags:
- name: Users
  description: Fetch and update
paths:
  /users/{id}:
    get:
      summary: User Details
      description: Given an ID, returns corresponding user
      parameters:
      - $ref: '#/parameters/path_id'
      tags:
      - Users
      responses:
        '200':
          description: OK
    put:
      summary: User Update
      description: 'Update a user

        '
      consumes:
      - application/json
      parameters:
      - $ref: '#/parameters/path_id'
      tags:
      - Users
      security:
      - api_token: []
      responses:
        '200':
          description: OK
  /users/{id}/projects:
    get:
      summary: User Projects
      description: 'Return projects as user has joined / followed

        '
      parameters:
      - $ref: '#/parameters/path_id'
      - $ref: '#/parameters/rule_details'
      - $ref: '#/parameters/project_type'
      - $ref: '#/parameters/page'
      - $ref: '#/parameters/per_page'
      tags:
      - Users
      responses:
        '200':
          description: OK
  /users/autocomplete:
    get:
      summary: User Autocomplete
      description: 'Given an string, returns users with names or logins starting with the search term

        '
      parameters:
      - $ref: '#/parameters/autocomplete_q'
      - $ref: '#/parameters/autocomplete_project_id'
      - $ref: '#/parameters/per_page'
      tags:
      - Users
      responses:
        '200':
          description: OK
  /users/me:
    get:
      summary: Users Me
      description: Fetch the logged-in user
      tags:
      - Users
      security:
      - api_token: []
      responses:
        '200':
          description: OK
  /users/{id}/mute:
    post:
      summary: Mute a User
      description: 'Make it so the authenticated user stops receiving notifications about

        activity by the user specified by {id}.

        '
      tags:
      - Users
      security:
      - api_token: []
      parameters:
      - $ref: '#/parameters/path_id'
      responses:
        '200':
          description: Returns an empty 200 response on success
        '404':
          description: Specified user does not exist
    delete:
      summary: Unmute a User
      description: Remove a mute on the user specified by {id}
      tags:
      - Users
      security:
      - api_token: []
      parameters:
      - $ref: '#/parameters/path_id'
      responses:
        '200':
          description: Returns an empty 200 response on success
        '404':
          description: Specified user does not exist
  /users/resend_confirmation:
    post:
      summary: User Resend Confirmation
      description: Resend an email confirmation
      consumes:
      - application/json
      tags:
      - Users
      security:
      - api_token: []
      responses:
        '200':
          description: OK
  /users/update_session:
    put:
      summary: User Update Session
      description: Update the logged-in user's session
      consumes:
      - application/json
      parameters:
      - name: body
        in: body
        description: Comment object
        schema:
          $ref: '#/definitions/PostUserUpdateSession'
      tags:
      - Users
      security:
      - api_token: []
      responses:
        '200':
          description: OK
definitions:
  PostUserUpdateSession:
    type: object
    properties:
      preferred_taxon_page_ancestors_shown:
        type: boolean
      preferred_taxon_page_place_id:
        type: integer
      preferred_taxon_page_tab:
        type: string
      prefers_skip_coarer_id_modal:
        type: boolean
      prefers_hide_obs_show_annotations:
        type: boolean
      prefers_hide_obs_show_projects:
        type: boolean
      prefers_hide_obs_show_tags:
        type: boolean
      prefers_hide_obs_show_observation_fields:
        type: boolean
      prefers_hide_obs_show_identifiers:
        type: boolean
      prefers_hide_obs_show_copyright:
        type: boolean
      prefers_hide_obs_show_quality_metrics:
        type: boolean
parameters:
  page:
    name: page
    type: string
    in: query
    description: Pagination `page` number
  autocomplete_q:
    name: q
    type: string
    in: query
    required: true
    description: Search by name (must start with this value) or by ID (exact match).
  autocomplete_project_id:
    name: project_id
    type: integer
    in: query
    description: Only show users with memberships to this project
  path_id:
    name: id
    in: path
    required: true
    type: integer
    description: ID of the record
  per_page:
    name: per_page
    type: string
    in: query
    description: 'Number of results to return in a `page`. The maximum value is generally

      200 unless otherwise noted

      '
  project_type:
    name: project_type
    type: string
    in: query
    enum:
    - traditional
    - collection
    - umbrella
    description: 'Specify the type of project to return

      '
  rule_details:
    name: rule_details
    type: string
    in: query
    enum:
    - true
    description: 'Return more information about project rules, for example return a full

      taxon object instead of simply an ID

      '
securityDefinitions:
  api_token:
    type: apiKey
    name: Authorization
    in: header