API docs by Redocly

Semios External API (1.0.0)

Download OpenAPI specification:

License: Semios Software User License Agreement

These docs describe the API in Semios Hub 0.146.1.

Authenticate with an API token generated in Semios Hub, sent as the api-token request header (not Authorization: Bearer). All endpoints are POST. Responses are scoped to the data the token’s user has permission to see. Assets the user cannot access, and assets that do not exist, are left out of a 200 response without a message. For assets the user can see, /v1/values-current and /v1/values-timeseries name the value types they left out in errors.

Get profile data

Returns the crops, insects, diseases, organizations and properties visible to the token’s user. Takes no request body.

Call this first. Every block and point in the response carries two arrays naming the value types available for that asset, already filtered to your permissions:

Array Feeds
data.properties[propertyId].blocks[blockId].valuesCurrent blocks.valuesRequested on /v1/values-current
data.properties[propertyId].blocks[blockId].valuesTimeseries blocks.valuesRequested on /v1/values-timeseries
data.properties[propertyId].points[lngLat].valuesCurrent points.valuesRequested on /v1/values-current
data.properties[propertyId].points[lngLat].valuesTimeseries points.valuesRequested on /v1/values-timeseries
data.properties[propertyId].irrigationZones[irrigationZoneId].valuesTimeseries irrigationZones.valuesRequested on /v1/values-timeseries

Irrigation zones only carry valuesTimeseries.

Insect value types end in an insect id: insectTrapCatches_todaySum_insectId7 in valuesCurrent, insectTrapCatches_7 or insectDegreeDays_7 in valuesTimeseries. data.insects lists every insect by insectId with its name, and data.diseases does the same for diseases.

The two vocabularies differ: valuesCurrent holds keys like humidity_in_pct, while valuesTimeseries holds humidity_IN. Send each endpoint only its own vocabulary, which is all its schema allows. Both endpoints reject any other key with a 422 that names it.

Block ids come from …blocks[blockId].blockId, point coordinates from …points[lngLat].lngLat, and irrigation zone ids from …irrigationZones[irrigationZoneId].irrigationZoneId.

Authorizations:
apiToken

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Get current values

Returns the latest value for each requested value type, by block, point or property.

A point key with no current value comes back as null; blocks and properties leave such a key out.

The keys valid for a given block or point are in that asset’s valuesCurrent array from /v1/profile-data — this schema lists every key available externally, which is a superset of what any one asset reports. Property-scope keys have no equivalent array; properties.valuesRequested lists every one.

If a requested value type is left out for a block, point or property you can see, the request still returns 200 with the rest of the data, and errors names the value type with the assets it was left out on and a reason, one line per value type and reason:

  • Omitted <valueType> on blocks 12, 13: not included in your permissions
  • Omitted <valueType> on points POINT(-120 45): not available for the asset

Assets you cannot see, and assets that do not exist, are left out without a message. errors is an empty array when nothing was left out.

Authorizations:
apiToken
Request Body schema: application/json
required
non-empty
object
object
object

Responses

Request samples

Content type
application/json
{
  • "blocks": {
    },
  • "points": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Get timeseries values

Returns a timeseries for each requested value type over the requested date range, by block, point or irrigation zone. data.irrigationZones is only in the response when the request asks for irrigationZones.

The keys valid for a given block, point or irrigation zone are in that asset’s valuesTimeseries array from /v1/profile-data — note that is a different array, and a different vocabulary, from the valuesCurrent one used by /v1/values-current. This schema lists every key available externally, along with the aggregation intervals each one accepts.

Weather and soil values come from a cache of recent data, about the last 30 days (daily weather often reaches back further). The part of a date range before that has no entries, and it is not reported as an error.

Raw readings (UNAGGREGATED) are only accepted by the irrigation interval and pressure keys; every other key takes the intervals listed in its schema.

Irrigation keys accept a limited date range per request:

  • up to 31 days: irrigationActivityIntervalsSemios_*, irrigationActivityPlannedIntervalsSemios_* and irrigationPressureSemios_*
  • up to 366 days: irrigationVolumeDurationSemios_* and irrigationPlannedVolumeDurationSemios_*

If the date range is longer than an irrigation key allows, that key is skipped and named in the errors array, and the rest of the request is still returned. Intervals always come back as start and end times whatever preferredAggregationInterval you ask for, and asking for daily pressure returns hourly pressure.

If a requested value type is left out for a block, point or irrigation zone you can see, the request still returns 200 with the rest of the data, and errors names the value type with the assets it was left out on and a reason, one line per value type and reason:

  • Omitted <valueType> on blocks 12, 13: not included in your permissions
  • Omitted <valueType> on irrigationZones 5: not available for the asset

Assets you cannot see, and assets that do not exist, are left out without a message. A value type you can read that has no data in the date range comes back empty and is not named. errors is an empty array when nothing was skipped or left out.

Put all the points or irrigation zones you need into one request instead of one request per asset: response time depends on the date range, not on how many assets you ask for.

Authorizations:
apiToken
Request Body schema: application/json
required
dateFrom
required
string
dateTo
required
string
object
object
object

Responses

Request samples

Content type
application/json
Example
{
  • "dateFrom": "2026-07-01T00:00:00.000",
  • "dateTo": "2026-07-04T23:59:59.999",
  • "blocks": {
    },
  • "points": {
    }
}

Response samples

Content type
application/json
Example
{
  • "errors": [ ],
  • "data": {
    }
}