Farmbrite Tasks API

openapi: 3.2.0
info:
  title: Farmbrite API Developers Documentation Tasks API
  description: '# Overview


    Welcome to the Farmbrite API. You can find out more about Farmbrite at

    www.farmbrite.com


    If you need help, check out our help center at help.farmbrite.com or email us at dev@farmbrite.com. ## API Reference


    The Farmbrite API allows authorized users programatic access to their account data in order to facilitate the integration of this data with other systems and service. The API is organized around REST standards. The API uses resource-oriented URLs and returns JSON-encoded responses. It uses standard HTTP response codes, authentication, and verbs. > Base URL


    ```

    https://api.farmbrite.com/v1


    ```


    # Authentication


    Farmbrite offers 2 authentication options for accessing the API both utilizing Personal Access Tokens (PATs) for enabling access to the API. Access Tokens (API Keys) are associated with an individual user in your account and inherit that user''s role and permissions. You can find the Access Token on the user profile page under API Key. When building an integration we recommend setting up a separate API user for the integration and changing the API KEY on a regular basis. Remember to keep your Access Tokens secret; treat them just like passwords! They act on your behalf when interacting with the API, with the same permissions and access as the user has. _Don''t hardcode them into your programs_. Instead, choose to store them as environment variables. ### Bearer Token


    To make a request to the API include the Authorization Bearer header with your request and include your Access Token (API KEY) as the value. Access Token and API KEY are used interchangeably through out the documentation. > Example cURL request authenticating with Bearer Token authentication


    ```

    curl https://api.farmbrite.com/v1/tasks \

    -H "Authorization: Bearer ACCESS_TOKEN"


    ```


    ### API Key


    Alternatively to using the Bearer Token authorization method, you can provide an API KEY as a header with your request. Use the header `api_key` with a value of your Access Token (API KEY). > Example cURL request authenticating with API Key header authentication


    ```

    curl https://api.farmbrite.com/v1/tasks \

    -H "api_key: ACCESS_TOKEN"


    ```


    # Errors


    Sadly, sometimes requests to the API fail. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code indicating the nature of the failure. | Code | Meaning | Description |

    | --- | --- | --- |

    | 200 | Success | The request was successful. If applicable the data it will be available in the data field at the top level of the response body. |

    | 400 | Bad Request | Typically caused by a missing or malformed parameter. Check the documentation and your request and try again. |

    | 401 | Unauthorized | No access token or an invalid access token was provided with the request. The error can also occur if the user or account is invalid or does not have access to this resource. |

    | 403 | Forbidden | The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you access resources that the user or account does not have access to. |

    | 404 | Not Found | Either the method and path supplied do not specify a known action or the object related to the request does not exist. |

    | 429 | Too Many Requests | You have exceeded one of the rate limits in the API. See the Rate Limits section for more information. |

    | 500 | Internal Server Error | There was a problem on Farmbrite''s side which was logged and reported to our technical team. You can retry, but if the problem continues please contact support. |


    Details about errors can sometimes also be found in the ''message'' property at the root level of the JSON response body. # Pagination


    In order to optimize performance, all list methods in the API will limit the total response data to a certain number of records and return the data in chunks (pages). API responses will include information about the total records available, the current page and total pages.'
  version: 1.0.0
  x-logo:
    url: https://static.farmbrite.com/assets/www/images/logo.png
    backgroundColor: '#FFFFFF'
    altText: Farmbrite
  termsOfService: https://www.farmbrite.com/terms
  contact:
    name: Farmbrite
    url: https://developers.farmbrite.com
    email: dev@farmbrite.com
servers:
- url: https://api.farmbrite.com/v1
security:
- bearerAuth: []
tags:
- name: Tasks
  description: 'Tasks are used to track things in Farmbrite that need to be done on your farm They can be assigned to different users in your account and can be associated to different resources (using the `reference_type` and `reference_id` properties**).**


    They can be assigned to different users in your account and can be associated with different resources, specifically:


    - Livestock `/animals`


    - Crop types `/plants`


    - Grow Locations `/plots`


    - Plantings `/crops`


    - Equipment `/tools`


    You can access and create resource specific items under that resource.


    For example`[GET] /animals/:animal_id/tasks` will fetch the tasks for this animal.


    Additionally, you can filter tasks by the email address of the user assigned to the task (or checklist item). Just pass in `?assigned_to_email=name@email.com` to the List Tasks endpoint'
paths:
  /tasks:
    post:
      tags:
      - Tasks
      summary: Create a Task
      description: 'Create a new task


        You can create a task at your account level using the `/tasks` path or under a supported resource (livestock, grow locations or equipment by using the path `/:resource_type/:resource_id/tasks`. For example`[GET] /animals/:id/tasks` will fetch the tasks for this animal.


        ### **Parameters**


        **title** **`REQUIRED`**


        The name of your task.


        ---


        **end_time** `OPTIONAL`


        Due DateTime of your task in `''YYYY-MM-DD HH:MM''` format.


        ---


        **assigned_to_id** `OPTIONAL`


        The ID or email address of the Farmbrite user to assign the item to.


        ---


        **description** `OPTIONAL`


        A summary description of the item.


        ---


        **reference_type** `OPTIONAL`


        Used to link the item to another resource. Supported values are:


        > "animal", "equipment", "plant", "location", "planting"


        When providing a `reference_type`, you should also provide a `reference_id`. This can also be accomplished by creating the schedule item through its parent resource path. eg; `/animals/:animal_id/tasks`.


        ---


        **reference_id** `OPTIONAL`


        A Farmbrite ID for the resource type that this record is associated with. This can also be accomplished by creating the schedule item through its parent resource path. eg; `/animals/:animal_id/tasks`.


        ---


        **status** `OPTIONAL`


        The status of the item. Options are determined by your account settings. See our help and documentation center for more information.


        ---


        **complete** `OPTIONAL`


        Boolean value that indicates whether the task is complete or not.


        ---


        **color** `OPTIONAL`


        A HEX color value to set the item''s color on the calendar or lis view.


        ---


        **checklist** `OPTIONAL`


        An array of hashes (JSON format) representing a list of items to complete in the following format:


        > \[ {"name": "Item 1", "assignee": "(Optional) user_id assigned to", "done": true }, ... \]


        ---


        **priority** `OPTIONAL`


        A numeric value between 1 and 5 representing the items priority.


        > {5 = "Highest", 4 = "High", 3 = "Medium", 2 = "Low", 1 = "Lowest"}


        ---


        **hours_spent** `OPTIONAL`


        A numeric (float) value used to track the amount of time spent on the task.


        ---


        **latitude** `OPTIONAL`


        A latitude value, with longitude, to tag a certain location on the map.


        ---


        **longitude** `OPTIONAL`


        A longitude value used if wanting to tag a certain location on the map.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                color: '#bdbdbd'
                checklist:
                - name: Item
                title: The title of your task
                description: ''
                assigned_to_id: Farmbrite User ID or Email
                priority: 3
                status: To Do
                end_time: 2022-04-01 11:30
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      operationId: postTasks
      x-operation-id-source: derived
    get:
      tags:
      - Tasks
      summary: List Tasks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - id: GUID
                  period: Does not repeat
                  color: '#bdbdbd'
                  checklist:
                  - name: Item 1
                    done: true
                  - name: Item 2
                    done: false
                  title: Task Title
                  description: Task Details
                  reference_id: ''
                  reference_type: ''
                  assigned_to_id: User ID
                  priority: 3
                  status: To Do
                  hours_spent: null
                  latitude: null
                  longitude: null
                  frequency: 1
                  todo: true
                  created_by: User
                  created_by_id: User Id
                  complete: false
                  updated_at: '2021-12-21 19:56:23'
                  created_at: '2021-12-21 19:56:23'
      operationId: getTasks
      x-operation-id-source: derived
  /tasks/{task_id}:
    get:
      tags:
      - Tasks
      summary: Retrieve a Task
      parameters:
      - name: task_id
        in: path
        schema:
          type: string
        required: true
        example: '{{task_id}}'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: GUID
                period: Does not repeat
                color: '#bdbdbd'
                checklist:
                - name: Item 1
                  done: true
                - name: Item 2
                  done: false
                title: Task Title
                description: Task Details
                reference_id: ''
                reference_type: ''
                assigned_to_id: User ID
                priority: 3
                status: To Do
                hours_spent: null
                latitude: null
                longitude: null
                frequency: 1
                todo: true
                created_by: User
                created_by_id: User Id
                complete: false
                updated_at: '2021-12-21 19:56:23'
                created_at: '2021-12-21 19:56:23'
      operationId: getTasksByTaskId
      x-operation-id-source: derived
    put:
      tags:
      - Tasks
      summary: Update a Task
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                title: Updated Task Title
                description: Description
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: task_id
        in: path
        schema:
          type: string
        required: true
        example: '{{task_id}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      operationId: putTasksByTaskId
      x-operation-id-source: derived
    delete:
      tags:
      - Tasks
      summary: Delete a Task
      parameters:
      - name: task_id
        in: path
        schema:
          type: string
        required: true
        example: '{{task_id}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      operationId: deleteTasksByTaskId
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer