farmOS Quantities API
Measurement quantities associated with logs
Documentation
Documentation
https://farmos.org/development/api/
Authentication
https://farmos.org/development/api/authentication/
OpenAPI Specification
openapi: 3.0.3
info:
title: 'farmOS JSON: Assets Quantities API'
description: 'The farmOS JSON:API provides access to farm assets, logs, plans, and records.
It follows the JSON:API specification (https://jsonapi.org/) with UUID-based
resource identifiers. The root endpoint at /api returns server metadata and
available resource types. Resource endpoints follow the pattern
/api/[entity-type]/[bundle].
farmOS is an open-source farm management and record-keeping system built on
Drupal. It supports self-hosted deployments and managed hosting via Farmier.
'
version: 2.x
contact:
name: farmOS Community
url: https://farmos.org/community/
license:
name: GNU General Public License v2.0
url: https://github.com/farmOS/farmOS/blob/main/LICENSE.txt
termsOfService: https://farmos.org/
servers:
- url: https://{farmOS-host}/api
description: Self-hosted farmOS instance
variables:
farmOS-host:
default: example.farmos.net
description: The hostname of your farmOS instance (self-hosted or Farmier-managed)
security:
- oauth2AuthorizationCode:
- farm_manager
- oauth2ClientCredentials:
- farm_manager
tags:
- name: Quantities
description: Measurement quantities associated with logs
paths:
/quantity/standard:
get:
operationId: listStandardQuantities
summary: List standard quantities
description: Measurement quantities associated with logs.
tags:
- Quantities
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/FilterField'
- $ref: '#/components/parameters/SortField'
- $ref: '#/components/parameters/IncludeRelated'
responses:
'200':
description: A collection of standard quantities
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/QuantityCollection'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createStandardQuantity
summary: Create a standard quantity
tags:
- Quantities
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/QuantityRequest'
responses:
'201':
description: Standard quantity created
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/QuantityResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/quantity/standard/{id}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: getStandardQuantity
summary: Get a standard quantity
tags:
- Quantities
responses:
'200':
description: A standard quantity
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/QuantityResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateStandardQuantity
summary: Update a standard quantity
tags:
- Quantities
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/QuantityRequest'
responses:
'200':
description: Updated standard quantity
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/QuantityResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteStandardQuantity
summary: Delete a standard quantity
tags:
- Quantities
responses:
'204':
description: Standard quantity deleted
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
QuantityData:
type: object
required:
- type
- attributes
properties:
type:
type: string
example: quantity--standard
id:
type: string
format: uuid
readOnly: true
attributes:
$ref: '#/components/schemas/QuantityAttributes'
relationships:
$ref: '#/components/schemas/QuantityRelationships'
links:
$ref: '#/components/schemas/JsonApiLinks'
JsonApiError:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
type: string
JsonApiRelationship:
type: object
properties:
data:
oneOf:
- $ref: '#/components/schemas/JsonApiRelationshipData'
- type: array
items:
$ref: '#/components/schemas/JsonApiRelationshipData'
- nullable: true
type: object
maxProperties: 0
links:
$ref: '#/components/schemas/JsonApiLinks'
QuantityAttributes:
type: object
properties:
measure:
type: string
description: Type of measurement (e.g., weight, volume, count, length, area, time, temperature, pressure, water_content, rating, ratio)
enum:
- weight
- volume
- count
- length
- area
- time
- temperature
- pressure
- water_content
- rating
- ratio
value:
type: object
description: Numeric value with decimal precision
properties:
numerator:
type: integer
denominator:
type: integer
decimal:
type: string
label:
type: string
description: Optional label for the quantity
inventory_adjustment:
type: string
description: How this quantity affects inventory (increment or decrement)
enum:
- increment
- decrement
- reset
QuantityRelationships:
type: object
properties:
units:
$ref: '#/components/schemas/JsonApiRelationship'
inventory_asset:
$ref: '#/components/schemas/JsonApiRelationship'
QuantityResponse:
type: object
properties:
data:
$ref: '#/components/schemas/QuantityData'
links:
$ref: '#/components/schemas/JsonApiLinks'
QuantityCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/QuantityData'
links:
type: object
meta:
type: object
properties:
count:
type: integer
QuantityRequest:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/QuantityData'
JsonApiLinks:
type: object
properties:
self:
type: string
format: uri
related:
type: string
format: uri
JsonApiRelationshipData:
type: object
properties:
type:
type: string
id:
type: string
format: uuid
parameters:
FilterField:
name: filter[field]
in: query
description: 'JSON:API filter parameter. Use dot notation for nested fields.
Example: filter[status]=pending or filter[timestamp][value]=1234567890&filter[timestamp][operator]=>=
'
schema:
type: string
PageSize:
name: page[limit]
in: query
description: Number of results per page
schema:
type: integer
minimum: 1
maximum: 50
default: 50
IncludeRelated:
name: include
in: query
description: 'Comma-separated list of related resources to include in the response.
Example: include=asset,quantity
'
schema:
type: string
SortField:
name: sort
in: query
description: 'Comma-separated list of fields to sort by. Prefix with - for descending.
Example: sort=-timestamp,name
'
schema:
type: string
PageOffset:
name: page[offset]
in: query
description: Offset for pagination
schema:
type: integer
minimum: 0
default: 0
ResourceId:
name: id
in: path
required: true
description: UUID of the resource
schema:
type: string
format: uuid
example: 3f1c2b4a-5d6e-7890-abcd-ef1234567890
responses:
NotFound:
description: Resource not found
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiError'
UnprocessableEntity:
description: Validation error
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiError'
Unauthorized:
description: Authentication required or token expired
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiError'
securitySchemes:
oauth2AuthorizationCode:
type: oauth2
description: 'OAuth2 Authorization Code grant for third-party integrations. Users
authorize the client application to access their farmOS data.
'
flows:
authorizationCode:
authorizationUrl: /oauth/authorize
tokenUrl: /oauth/token
scopes:
farm_manager: Full management access to the farm
farm_worker: Worker-level access to farm records
farm_viewer: Read-only access to farm records
oauth2ClientCredentials:
type: oauth2
description: 'OAuth2 Client Credentials grant for machine-to-machine authentication.
Used when no user account is required.
'
flows:
clientCredentials:
tokenUrl: /oauth/token
scopes:
farm_manager: Full management access to the farm
farm_worker: Worker-level access to farm records
farm_viewer: Read-only access to farm records
externalDocs:
description: farmOS API Documentation
url: https://farmos.org/development/api/