iNaturalist Projects API

openapi: 3.2.0
info:
  title: iNaturalist Projects API
  description: '# https://api.inaturalist.org/v1/


    iNaturalist 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.'
  version: 1.3.0
servers:
- url: /v1
tags:
- name: Projects
  description: Search and fetch projects and members
paths:
  /projects:
    get:
      summary: Project Search
      description: 'Given zero to many of following parameters, returns projects

        matching the search criteria'
      parameters:
      - $ref: '#/components/parameters/autocomplete_q_not_required'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/not_id'
      - $ref: '#/components/parameters/lat'
      - $ref: '#/components/parameters/lng'
      - $ref: '#/components/parameters/associated_place_id'
      - $ref: '#/components/parameters/projects_radius'
      - $ref: '#/components/parameters/featured'
      - $ref: '#/components/parameters/noteworthy'
      - $ref: '#/components/parameters/projects_site_id'
      - $ref: '#/components/parameters/rule_details'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/member_id'
      - $ref: '#/components/parameters/has_params'
      - $ref: '#/components/parameters/has_posts'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/projects_order_by'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an array of projects

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getProjects
      x-operation-id-source: derived
  /projects/{id}:
    get:
      summary: Project Details
      description: 'Given an ID, or an array of IDs in comma-delimited format, returns

        corresponding projects. A maximum of 100 results will be returned'
      parameters:
      - $ref: '#/components/parameters/path_multi_id_or_slug'
      - $ref: '#/components/parameters/rule_details'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an array of projects

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getProjectsById
      x-operation-id-source: derived
  /projects/{id}/join:
    post:
      summary: Projects Join
      description: Join a project
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      operationId: postProjectsByIdJoin
      x-operation-id-source: derived
  /projects/{id}/leave:
    delete:
      summary: Projects Leave
      description: Leave a project
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      operationId: deleteProjectsByIdLeave
      x-operation-id-source: derived
  /projects/{id}/members:
    get:
      summary: Project Members
      description: Given an ID, return members of the project
      parameters:
      - $ref: '#/components/parameters/path_id'
      - name: role
        in: query
        description: Membership role
        schema:
          type: string
          enum:
          - curator
          - manager
      - $ref: '#/components/parameters/skip_counts'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an results array of projects

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMembersResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getProjectsByIdMembers
      x-operation-id-source: derived
  /projects/{id}/membership:
    get:
      summary: Membership of current user
      description: 'Given an ID, or an array of IDs in comma-delimited format, return the details of the

        authenticated user''s membership in these projects'
      parameters:
      - $ref: '#/components/parameters/path_multi_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      operationId: getProjectsByIdMembership
      x-operation-id-source: derived
  /projects/{id}/subscriptions:
    get:
      deprecated: true
      summary: Project Subscriptions
      description: '[Deprecated] Subscriptions to projects are managed through joining and

        leaving projects, so this will not return any useful information.


        Given an ID, return subscription of the current user'
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      operationId: getProjectsByIdSubscriptions
      x-operation-id-source: derived
  /projects/{id}/add:
    post:
      summary: Project Add
      description: Add an observation to a project
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProjectAdd'
        description: ProjectObservation object
      operationId: postProjectsByIdAdd
      x-operation-id-source: derived
  /projects/{id}/remove:
    delete:
      summary: Project Add
      description: Remove an observation from a project
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProjectAdd'
        description: ProjectObservation object
      operationId: deleteProjectsByIdRemove
      x-operation-id-source: derived
  /projects/autocomplete:
    get:
      summary: Project Autocomplete
      description: Given an string, returns projects with titles starting with the search term
      parameters:
      - $ref: '#/components/parameters/autocomplete_q'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/not_id'
      - $ref: '#/components/parameters/lat'
      - $ref: '#/components/parameters/lng'
      - $ref: '#/components/parameters/associated_place_id'
      - $ref: '#/components/parameters/projects_radius'
      - $ref: '#/components/parameters/featured'
      - $ref: '#/components/parameters/noteworthy'
      - $ref: '#/components/parameters/projects_site_id'
      - $ref: '#/components/parameters/rule_details'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/member_id'
      - $ref: '#/components/parameters/has_params'
      - $ref: '#/components/parameters/has_posts'
      - $ref: '#/components/parameters/per_page'
      tags:
      - Projects
      responses:
        '200':
          description: 'Returns an object with metadata and an results array of places

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getProjectsAutocomplete
      x-operation-id-source: derived
  /subscriptions/project/{id}/subscribe:
    post:
      summary: Project Subscribe
      description: 'Toggles current user''s subscription to this project. If the logged-in

        user is not subscribed, POSTing here will subscribe them. If they are already

        subscribed, this will remove the subscription'
      parameters:
      - $ref: '#/components/parameters/path_id'
      tags:
      - Projects
      security:
      - api_token: []
      responses:
        '200':
          description: OK
      operationId: postSubscriptionsProjectByIdSubscribe
      x-operation-id-source: derived
components:
  parameters:
    path_id:
      name: id
      in: path
      required: true
      description: ID of the record
      schema:
        type: integer
    associated_place_id:
      name: place_id
      in: query
      description: Must be associated with this place
      schema:
        type: array
        items:
          type: string
    not_id:
      name: not_id
      in: query
      description: Must not have this ID
      schema:
        type: array
        items:
          type: string
        minimum: 1
    lng:
      name: lng
      in: query
      description: 'Must be within a {`radius`} kilometer circle around this lat/lng

        (*lat, *lng, radius)

        '
      schema:
        type: number
        format: double
    has_params:
      name: has_params
      in: query
      description: Must have search parameter requirements
      schema:
        type: boolean
    projects_order_by:
      name: order_by
      in: query
      description: Sort field
      schema:
        type: string
        enum:
        - recent_posts
        - created
        - updated
        - distance
        - featured
    lat:
      name: lat
      in: query
      description: 'Must be within a {`radius`} kilometer circle around this lat/lng

        (*lat, *lng, radius)

        '
      schema:
        type: number
        format: double
    path_multi_id:
      name: id
      in: path
      required: true
      description: Must have this ID
      schema:
        type: array
        items:
          type: integer
    autocomplete_q_not_required:
      name: q
      in: query
      description: Search by name (must start with this value) or by ID (exact match).
      schema:
        type: string
    page:
      name: page
      in: query
      description: Pagination `page` number
      schema:
        type: string
    projects_radius:
      name: radius
      in: query
      description: 'Must be within a {`radius`} kilometer circle around this lat/lng

        (*lat, *lng, radius). Defaults to 500km

        '
      schema:
        type: string
    id:
      name: id
      in: query
      description: Must have this ID
      schema:
        type: array
        items:
          type: string
        minimum: 1
    rule_details:
      name: rule_details
      in: query
      description: 'Return more information about project rules, for example return a full

        taxon object instead of simply an ID

        '
      schema:
        type: string
        enum:
        - true
    projects_site_id:
      name: site_id
      in: query
      description: 'Site ID that applies to `featured` and `noteworthy`. Defaults to the site

        of the authenticated user, or to the main iNaturalist site

        https://www.inaturalist.org

        '
      schema:
        type: integer
    noteworthy:
      name: noteworthy
      in: query
      description: Must be marked noteworthy for the relevant site
      schema:
        type: string
        enum:
        - true
    autocomplete_q:
      name: q
      in: query
      required: true
      description: Search by name (must start with this value) or by ID (exact match).
      schema:
        type: string
    per_page:
      name: per_page
      in: query
      description: 'Number of results to return in a `page`. The maximum value is generally

        200 unless otherwise noted

        '
      schema:
        type: string
    skip_counts:
      name: skip_counts
      in: query
      description: 'If counts are not needed, consider setting this to true to save on

        processing time, resulting in faster responses

        '
      schema:
        type: boolean
        default: false
    type:
      name: type
      in: query
      description: Projects must be of this type
      schema:
        type: array
        items:
          type: string
        enum:
        - collection
        - umbrella
    featured:
      name: featured
      in: query
      description: Must be marked featured for the relevant site
      schema:
        type: string
        enum:
        - true
    path_multi_id_or_slug:
      name: id
      in: path
      required: true
      description: Must have this ID or slug
      schema:
        type: array
        items:
          type: string
    has_posts:
      name: has_posts
      in: query
      description: Must have posts
      schema:
        type: boolean
    member_id:
      name: member_id
      in: query
      description: Project must have member with this user ID
      schema:
        type: integer
  schemas:
    BaseResponse:
      type: object
      properties:
        total_results:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    User:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        id:
          type: integer
        icon:
          type: string
        icon_url:
          type: string
        identifications_count:
          type: integer
        journal_posts_count:
          type: integer
        login:
          type: string
        name:
          type: string
        observations_count:
          type: integer
        orcid:
          type: string
        roles:
          type: array
          items:
            type: string
            enum:
            - admin
            - app owner
            - curator
        site_id:
          type: integer
        species_count:
          type: integer
        spam:
          type: boolean
        suspended:
          type: boolean
    Project:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        slug:
          type: string
    ProjectMember:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        role:
          type: string
          enum:
          - curator
          - manager
        observations_count:
          type: integer
        taxa_count:
          type: integer
        user:
          $ref: '#/components/schemas/User'
    ProjectMembersResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/ProjectMember'
    ProjectsResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - required:
        - results
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/Project'
    PostProjectAdd:
      type: object
      properties:
        observation_id:
          type: integer
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  securitySchemes:
    api_token:
      type: apiKey
      name: Authorization
      in: header