Welcome

Overview

The EU-FarmBook Public API (v2) lets external systems authenticate, push Knowledge Objects (documents and media with metadata) into EU-FarmBook, and read back what their project has uploaded. It is the programmatic alternative to the web uploader — best suited to bulk or automated contributions.

Version 1 of the API is retired (it returns 410 Gone). Use the /api/... (v2) endpoints documented here.

Before you begin

Anyone can register for an EU-FarmBook account, but uploading through the API also requires a role on the project you are contributing to:

Ambassador — granted by the EU-FarmBook team and able to contribute to all projects. To request it, send us a message via the Contact us form.
Coordinator or Contributor — granted per project by an Ambassador. To request access to a specific project, contact its Ambassador.

Without one of these roles on the target project, uploads return 403.

Base URL

Production environment: https://api-public.prd.farmbook.ugent.be

Development environment: https://api-public.dev.farmbook.ugent.be

Authentication model

Obtain an access token from /api/authentication/token, then send it on every protected call as an Authorization: Bearer <access_token> header together with X-User-UUID: <uuid>.

Access tokens are valid for 4 hours. When a token expires, request a new one from the same endpoint — the Public API does not return a refresh token.

Typical flow

Publishing a Knowledge Object is a short, ordered sequence:

Get an access token and your UUID — Authentication.
Find a project_id you can contribute to — Authentication.
Upload the file and keep its database_id (used next as ko_file_id) — Upload.
Upload the metadata referencing that ko_file_id — Upload.
Read back what you published — Project / Query.

The validated fields (category, topics, themes, …) must use values from the Metadata vocabularies. Uploaded files and submitted URLs are also checked before they are accepted.

Common errors

403 — you are not a Coordinator or Contributor on that project.
422 — invalid body, unsupported vocabulary value, or a file/URL that did not pass the upload check.
410 — a retired v1 endpoint; use the v2 paths documented here.

Quick start

Authenticate and list the projects you can contribute to:

# 1. Get a token
curl -X POST "https://api-public.prd.farmbook.ugent.be/api/authentication/token" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.org", "password": "••••••••"}'

# 2. Use it (access_token + uuid from the response)
export EUF_TOKEN="<access_token>"
export EUF_UUID="<uuid>"

curl "https://api-public.prd.farmbook.ugent.be/api/authentication/projects" \
  -H "Authorization: Bearer $EUF_TOKEN" \
  -H "X-User-UUID: $EUF_UUID"

Authentication

Every write endpoint is protected. Exchange your EU-FarmBook credentials for an access token, then send that token as a Bearer header together with your user UUID (X-User-UUID) on each authenticated request.

Get a token

POST/api/authentication/tokenPublic

Use your EU-FarmBook username (email) and password to obtain an access token and your user UUID. The token authenticates subsequent calls; the UUID is sent as the X-User-UUID header.

Name	In	Type	Required	Description
`email`	body	string	Yes	Your EU-FarmBook account email.
`password`	body	string	Yes	Your EU-FarmBook account password.

Request body

{
  "email": "you@example.org",
  "password": "••••••••"
}

curl -X POST "https://api-public.prd.farmbook.ugent.be/api/authentication/token" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.org", "password": "••••••••"}'

Example response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "uuid": "1f3c9b27-7e4a-4d2b-9c5e-8a1f0b6d4e21"
}

List your projects

GET/api/authentication/projectsRequires auth

Return the projects you may contribute to. Uploads target a specific project_id, so call this first to discover the ids you have access to.

Name	In	Type	Required	Description
`Authorization`	header	Bearer <access_token>	Yes	—
`X-User-UUID`	header	string	Yes	The uuid returned by /authentication/token.

curl "https://api-public.prd.farmbook.ugent.be/api/authentication/projects" \
  -H "Authorization: Bearer $EUF_TOKEN" \
  -H "X-User-UUID: $EUF_UUID"

Example response

[
  { "project_id": "6630f1c2a1b2c3d4e5f60718", "project_name": "AgroForward" },
  { "project_id": "6630f1c2a1b2c3d4e5f60722", "project_name": "SoilHealth EU" }
]

Upload

Publishing a Knowledge Object (KO) is a two-step flow: first upload the file and capture its database_id, then upload the metadata referencing that id as ko_file_id. Files and external URLs are checked before they are accepted, so uploads may take a little longer and can be rejected when the content is not suitable for EU-FarmBook. Both calls require project access — without it they return 403. Provide exactly one of files[] or knowledge_object_url in the metadata.

Upload a KO file

POST/api/upload/knowledge_object_fileRequires auth

Upload the binary file for a Knowledge Object as multipart/form-data (field ufile). The file is checked before it is stored. If it passes, the returned database_id is used as ko_file_id when you upload the metadata. Skip this step if your KO is an external URL.

Name	In	Type	Required	Description
`project_id`	query	string	Yes	The target project id.
`upload_source`	query	string	No	Optional source tag for the upload.
`Authorization`	header	Bearer <access_token>	Yes	—
`X-User-UUID`	header	string	Yes	—
`ufile`	body	file (multipart/form-data)	Yes	The file to upload.

curl -X POST "https://api-public.prd.farmbook.ugent.be/api/upload/knowledge_object_file?project_id=$EUF_PROJECT" \
  -H "Authorization: Bearer $EUF_TOKEN" \
  -H "X-User-UUID: $EUF_UUID" \
  -F "ufile=@soil-sampling-guide.pdf"

Example response

{
  "database_id": "6631aa02f0c1e2d3a4b5c6d7",
  "filename": "soil-sampling-guide.pdf",
  "message": "File uploaded successfully"
}

Upload KO metadata

POST/api/upload/knowledge_object_metadataRequires auth

Create the Knowledge Object by posting its metadata. If you submit an external knowledge_object_url instead of files, that URL is checked before the metadata is stored. Validated enum fields (category, subcategories, topics, themes, intended_purposes, locations, license, languages) must use values from the Metadata vocabulary endpoints below. Dates use the DD-MM-YYYY format.

Name	In	Type	Required	Description
`project_id`	query	string	Yes	—
`upload_source`	query	string	No	—
`Authorization`	header	Bearer <access_token>	Yes	—
`X-User-UUID`	header	string	Yes	—
`body`	body	KnowledgeObjectMetadata	Yes	See the metadata field reference below.

Request body

{
  "title": "Practical guide to soil sampling",
  "subtitle": "Field protocols for representative samples",
  "description": "A step-by-step guide to collecting soil samples ...",
  "keywords": ["soil", "sampling", "agronomy"],
  "creators": [
    { "creator_type": "person", "name": "Jane Doe", "email": "jane@example.org", "orcid": "0000-0002-1825-0097" },
    { "creator_type": "organization", "name": "Example Research Institute", "email": null }
  ],
  "date_of_completion": "31-05-2026",
  "intended_purposes": ["Practice"],
  "locations": [{ "name": "Belgium", "nuts_level": 0 }],
  "category": "Crop production",
  "subcategories": ["Soil management"],
  "topics": ["Crop farming"],
  "themes": ["Soil"],
  "license": "CC BY 4.0",
  "files": [
    { "ko_file_id": "6631aa02f0c1e2d3a4b5c6d7", "language": "en", "translations": [], "subtitles": [], "doi": null }
  ]
}

curl -X POST "https://api-public.prd.farmbook.ugent.be/api/upload/knowledge_object_metadata?project_id=$EUF_PROJECT" \
  -H "Authorization: Bearer $EUF_TOKEN" \
  -H "X-User-UUID: $EUF_UUID" \
  -H "Content-Type: application/json" \
  -d @metadata.json

Example response

{
  "database_id": "6631ab90f0c1e2d3a4b5c700",
  "message": "Knowledge object created successfully"
}

Project

Read back the Knowledge Objects your project has already uploaded.

Get your project's KO metadata

POST/api/project/knowledge_object_metadataRequires auth

Retrieve the metadata for all Knowledge Objects uploaded under a project you have access to.

Name	In	Type	Required	Description
`project_id`	query	string	Yes	—
`Authorization`	header	Bearer <access_token>	Yes	—
`X-User-UUID`	header	string	Yes	—

curl -X POST "https://api-public.prd.farmbook.ugent.be/api/project/knowledge_object_metadata?project_id=$EUF_PROJECT" \
  -H "Authorization: Bearer $EUF_TOKEN" \
  -H "X-User-UUID: $EUF_UUID"

Example response

[
  {
    "database_id": "6631ab90f0c1e2d3a4b5c700",
    "title": "Practical guide to soil sampling",
    "category": "Crop production",
    "topics": ["Crop farming"],
    "date_of_completion": "31-05-2026"
  }
]

Query

Filter Knowledge Object metadata by an arbitrary criteria object. An empty body ({}) returns everything you may see.

Query KO metadata with filters

POST/api/query/metadataRequires auth

Retrieve Knowledge Object metadata matching a free-form criteria filter. Send {} to omit filtering.

Name	In	Type	Required	Description
`Authorization`	header	Bearer <access_token>	Yes	—
`X-User-UUID`	header	string	Yes	—
`criteria`	body	object	No	Filter object; defaults to {}.

Request body

{
  "category": "Crop production",
  "topics": ["Crop farming"]
}

curl -X POST "https://api-public.prd.farmbook.ugent.be/api/query/metadata" \
  -H "Authorization: Bearer $EUF_TOKEN" \
  -H "X-User-UUID: $EUF_UUID" \
  -H "Content-Type: application/json" \
  -d '{"category": "Crop production", "topics": ["Crop farming"]}'

Example response

[
  {
    "database_id": "6631ab90f0c1e2d3a4b5c700",
    "title": "Practical guide to soil sampling",
    "category": "Crop production"
  }
]

Metadata vocabularies

The validated enum fields on a Knowledge Object must use values from these public vocabulary endpoints. They require no authentication, are case-insensitive, and are cached server-side (~24h). All nine follow the same shape — one representative call is shown below.

Endpoint	Returns
`GET /api/metadata/topics`	Allowed topics.
`GET /api/metadata/themes`	Allowed themes.
`GET /api/metadata/categories`	Allowed categories.
`GET /api/metadata/subcategories`	Allowed subcategories.
`GET /api/metadata/subcategories/details`	Subcategories with their parent category.
`GET /api/metadata/licenses`	Allowed licenses.
`GET /api/metadata/locations`	Allowed locations (with NUTS levels).
`GET /api/metadata/intended_purposes`	Allowed intended purposes.
`GET /api/metadata/languages`	Allowed language codes.

Get a vocabulary

GET/api/metadata/topicsPublic

Representative vocabulary request. Swap the final path segment for any of the nine vocabularies listed above.

curl "https://api-public.prd.farmbook.ugent.be/api/metadata/topics"

Example response

["Crop farming", "Livestock", "Forestry", "Economics", "Environment", "Society"]

API status

Unauthenticated health checks for the public API and the EU-FarmBook database.

Public API status

GET/api/status/api_statusPublic

A simple check on the Public API status.

curl "https://api-public.prd.farmbook.ugent.be/api/status/api_status"

Example response

{ "status": "ok" }

Database status

GET/api/status/db_statusPublic

A simple check on the status of the EU-FarmBook database.

curl "https://api-public.prd.farmbook.ugent.be/api/status/db_status"

Example response

{ "status": "ok" }

Metadata field reference

Curated overview of the KnowledgeObjectMetadata body used by POST /api/upload/knowledge_object_metadata. Provide exactly one of files or knowledge_object_url. See the full schema for nested types and every optional field.

Field	Type	Required	Description
`title`	string	Yes	Title of the Knowledge Object.
`subtitle`	string	Yes	Short subtitle / tagline.
`description`	string	Yes	Full description.
`keywords`	string[]	Yes	Free-text keywords.
`creators`	Creator[]	Yes	{ creator_type: person \| organization, name, email?, orcid? }.
`date_of_completion`	string	Yes	Completion date in DD-MM-YYYY format.
`intended_purposes`	string[]	Yes	From /api/metadata/intended_purposes.
`locations`	Location[]	Yes	{ name, nuts_level? } — names from /api/metadata/locations.
`category`	string	Yes	From /api/metadata/categories.
`subcategories`	string[]	Yes	From /api/metadata/subcategories.
`topics`	string[]	Yes	From /api/metadata/topics.
`themes`	string[]	Yes	From /api/metadata/themes.
`license`	string \| null	Yes	From /api/metadata/licenses (may be null).
`files`	File[]	No	Provide exactly one of files or knowledge_object_url. { ko_file_id, language, translations?, subtitles?, doi? }.
`knowledge_object_url`	object	No	For URL-based KOs. { url, language, translations?, subtitles?, doi? }.
`collection`	string \| null	No	Optional collection name.
`knowledge_object_version`	string \| null	No	Optional version label.
`contributor_custom_metadata`	object	No	Free-form custom key/value metadata.

Full reference

This page is a curated guide. For the exhaustive, always-current schema — every field, enum and response code — use the interactive docs generated from the live service: