API docs by Redocly

VelHerd - API documentation (1.0.0)

Download OpenAPI specification:Download

You can use VelHerd API if you have account on VelHerd web site.

Reference

Reference > Introduction

General info

You can use VelHerd API if you have account on VelHerd web site.

VelHerd API is HTTP JSON API. That means all requests and responses are sent via HTTP protocol (secured with SSL). All data in requests and responses present in HTTP Body in JSON format.

VelHerd API is based on REST principles. You have to be authenticated and call the simple HTTPs request on the URLs specified below. The following documentation covers core resources that are used to manipulate the main entities. First of all, read basic instructions to start using the API.

Very basics of HTTP REST concepts

Allowed HTTPs request typesemail

  • GET — Get a resource or list of resources

  • POST — To create or update resource

  • PUT — To create or update resource

  • DELETE — To delete resource

Usual HTTP response codes

  • 200 OK — the request was successful.

  • 201 Created — the request was successful and a resource was created.

  • 204 No Content — the request was successful but there is no representation to return (i.e. the response is empty).

  • 400 Bad Request — the request could not be understood or was missing required parameters.

  • 401 Unauthorized — authentication failed or user doesn't have permissions for requested operation.

  • 403 Forbidden — access denied.

  • 404 Not Found — resource was not found.

  • 422 Unprocessable Entity - the request was well-formed but was unable to be followed due to semantic errors.

  • 503 Service Unavailable — service is temporary unavailable (e.g. scheduled Platform Maintenance). Try again later.

Methods

Useful tools

Important notice! — read before start using API

  1. You should add HTTP Header Content-Type: application/json for all POST and PUT requests. Else, request would be dropped.

  2. VelHerd API works only via HTTPS (SSL). Important! — check that you use https:// in all requests (especially in Authorization request).

  3. In case of wrong request or data, API gives you response with HTTP Error Code and detailed error description (if available). Please read it carefully.

  4. Naming convention for OBJECT in requests: you need to use plural object name in snake_case:

Reference > Authentication

The user should obtain a USER_API_TOKEN token that is required for all subsequent requests. USER_API_TOKEN is a string, that should be used to generate a JSON Web Token (JWT).

You can generate USER_API_TOKEN on the user settings page (http://https://velherd.com/users/ID/edit_user) in the VelHerd system.

When you generate a token, you must copy it and save it for future use.

After generating USER_API_TOKEN you can use it to generate a JWT.

Reference > Authorization

For authorization, you must generate a JWT. Send a request to https://velherd.com/api/access_tokens with USER_API_TOKEN in body.

{"integration_token": {"token": "USER_API_TOKEN"}}

In response, you will have a JWT (access_token) that is available for some time (expires_in).

{
    "access_token": 
"eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJjb21wYW55X2lkIjoyLCJleHAiOjE3NTAyNDk2NzZ9.b3uTIBUYOEHwVFmVkrbWOAXRX9u-0osG0fBPVqU0Q1A", 
    "expires_time": 7200,
    "expires_in": "2025-06-18T15:27:56.000+03:00"
}

After generating a JWT (access_token), you can use it in your request. In the header, you must have Authorization or X-Authorization with value Bearer access_token

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJjb21wYW55X2lkIjoyLCJleHAiOjE3NTAyNDk2NzZ9.b3uTIBUYOEHwVFmVkrbWOAXRX9u-0osG0fBPVqU0Q1A

JWToken

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "integration_token": {
    }
}

API endpoints

List of VelHerd API endpoints

API endpoints > Farm Units

https://velherd.com/api/v1/farm_units

FarmUnit has next parameters

  • (readonly) id — VelHerd ID of FarmUnit

  • name — name of FarmUnit

  • description — country_code of AdminRegion

  • external_id — фn optional identifier used to reference this resource in an external system

  • active — does FarmUnit is active and shows in list

  • (readonly) created_at

  • (readonly) updated_at

Acceptable methods

  • Ids

  • Changes

  • Single Resource

  • Create Resource

  • Update Resource

  • Delete Resource

Filters by

id, name, active, external_id

Order by

id, name

get_farm_units_with_filter

header Parameters
Authorization
string
Example: Bearer JWToken

Responses

create_farm_unit

header Parameters
Authorization
string
Example: Bearer JWToken
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

get_farm_unit_ids

header Parameters
Authorization
string
Example: Bearer JWToken

Responses

get_farm_unit

header Parameters
Authorization
string
Example: Bearer JWToken

Responses

update_farm_unit

header Parameters
Authorization
string
Example: Bearer JWToken
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

destroy_farm_unit

header Parameters
Authorization
string
Example: Bearer JWToken

Responses