Cool Farm Platform - API User Guide
Section 1: Getting Started
In order to use the CFP API service, you will first need to be a CFA member and sign an API licence agreement. Contact support@coolfarmtool.org to find out more.
Once you have an API licence, a CFP admin will set you up with the correct permissions, so that you can see our online documentation on our API Docs Page, built with OpenAPI (Swagger)
You will then be able to use the Try it out features on the API Docs page to generate an API key, so that you can make calls from external sources.
Read-only mode
If you do not have an API licence, you can still view the API docs page and see information about our API endpoints and schemas by viewing in read-only mode. In read-only mode, schemas and endpoints are viewable, but the Try it out function is disabled so that no calls can be made.
Generating an API Key
To make external API calls to the CFP API, you will first need an API key, which you can generate for yourself from the API docs page.
To request access to the API docs page, you will need to be granted permission as an API user. This will be done for you when you are set up, but in case of issues, please contact support@coolfarmtool.org.
Once you have been permissioned as an API user, you need to generate an API key
- Navigate to the API docs page https://cfp.coolfarm.org/api-docs
- Use the create API key endpoint shown below:
Use the Try it out button to run the call
Give your API Key a name.
The API key is returned as shown below. For Data security reasons, we do not store the key, and it can not be reissued. Store API keys securely using environment variables or a secrets manager - never hard-code them in your source code or commit them to version control.
Section 2: API docs page
We provide an API docs page where you can find lots of useful information about the endpoints that we provide on CFP.
The API Docs page can be found here. https://cfp.coolfarm.org/api-docs
You can use our API docs page to
- Review all the endpoints that are available to you
- Find the URL of each of our endpoints
- View example JSONs for each endpoint
- View the Schemas for the endpoints that you wish to use.
- Understand all the variables and permitted values for each endpoint
- Use the “Try it” out function to make trial calls
- Understand responses and error codes returned by CFP
How to see your API endpoints
When you log into API docs you will automatically be able to view the API endpoints that are available to you.
As an API License holder you should be able to see and use endpoints relating to:
- Assessments - allows you to create and manage assessments or run calculations without creating an assessment.
- Soil - allows you to retrieve soil classification information for any location
- Farm - allows you to create and manage your farms.
- API Keys - allows you to create and manage your API keys
The screenshot below shows what you should see when you log into the API docs page as an API license holder. If you don't see this, contact support@coolfarmtool.org to have your permissions updated.
How to find the API endpoint URLs
- Navigate to the API Docs page
- Find the relevant endpoint
- Hover over the right-hand side next to the expand arrow to reveal the clipboard icon
4. Click on the Icon to copy the endpoint URL. e.g. https://api.cfp.coolfarm.org/assessment/create-and-run5. Paste to your desired location
API endpoint examples
When you expand each endpoint section on the API docs page, you will see an example of the JSON schema for the request body and the response. These can be used to help to format your own requests and understand what you see in the response body.
Where to find the example request body
Where to find the example response
How to view Schemas
There are 2 ways to view the schemas for the endpoints.
- The first is to use the Schema function on the API docs page and
- The second is to use the specific Get Schemas endpoint
Section 3: Creating tailored examples using the web app
If you want to know how a specific section should be formatted in an API call, you can create an assessment and populate the sections of interest in the web app. Once submitted, you can use the fetch assessment endpoint to view how the input data should be formatted in the API call.
Create an assessment in the web app
Complete the sections of interest in the web app and submit the assessment. The example below is for the Fertiliser category.
Copy the assessment ID
Go to the API docs, find the Fetch assessment endpoint,
Use the Try it out function
Paste in your assessment ID
Hit Execute
Scroll to the response body section
Look for the input data object within the response body
Look for the relevant object (fertiliser in this example).
Section 4: Using the web app and Fetch assessment endpoint to review example schemas with blank entries.
One tip for creating examples is to go into the web app and create an assessment, leaving various sections blank. You can then use the fetch assessment endpoint to review how that assessment's input data will look in a JSON file.
You can follow this process.
- Create an assessment with some blank sections. Crop details and Residue are required sections; everything else can be left blank
- Copy the assessment ID.
- Go to the API docs page
- Find the fetch assessment endpoint, use the Try it out function and paste in your assessment ID
- Execute
- Download the JSON or view in the API docs page
- Look for the input data object
- Review the format of completed and empty objects. In the example below, I have completed the residue, machinery and waste water sections, the others are blank. You can experiment by completing which ever sections you choose in the web app.
"inputData": { "nonCrop": { "hedges": [], "intercrops": [], "shadeTrees": [] }, "residue": { "aboveGroundResidue": null, "residueManagementPractice": "burning" }, "machinery": { "machineryUse": [ { "label": "this is a free text field ", "fuelUse": "diesel (100% mineral diesel)", "machine": "Disc gang", "numberMachineryOperations": 5 } ] }, "pesticide": { "applications": [] }, "transport": { "transports": [] }, "fertiliser": { "fertilisers": [] }, "fuelEnergy": { "usages": [] }, "irrigation": { "events": [] }, "wasteWater": { "treatments": [ { "oxygenDemand": { "unit": "kg per litre", "value": 9 }, "oxygenDemandType": "Biochemical", "treatmentProcess": "None - unspecified aquatic environment", "wasteWaterVolume": { "unit": "litres", "value": 10000 } } ] }, "cropDetails": { "area": { "unit": "hectares", "value": 10 }, "cropType": "Alfalfa", "farmGate": { "unit": "tonnes", "value": 100 }, "soilType": "Fine", "cropYield": { "unit": "tonnes", "value": 100 }, "assessmentYear": 2024, "sandPercentage": 5 }, "refrigerants": { "equipments": [] }, "seedProduction": { "seedBought": null }, "steadyStateSoc": { "landUseHistory": { "changes": [] } }, "landUseChangeBiomass": { "forestChanges": null } } },
Section 5 : API endpoints (billable and non billable) TBC
We are not currently billing for API usage on the Cool Farm Platform, as we want to give API license holders sufficient time to review and become familiar with the new endpoints.
Further communication will follow shortly, including details on which endpoints will be billable and from what date.
Section 6: API response guide.
Users of the CFTool API service will notice that there are some differences in the way that the API responses are structured. We have now included some more useful sections. the flowing is a summary for the "Calculate" and "Create and run" endpoints
Run metadata
Provides info on the assessment run
{ "runMetadata": { "subCategory": "Barley", "assessmentYear": "2024" },
Results summary
Provides a top line view of your balance, emissions and removals in CO2e
"resultSummary": { "assessmentYear": { "CO2eq": { "emissions": 791495.0401663767, "removals": -2770643.52, "balance": -1979148.4798336234
Results Disaggregated
Details all the disaggregated results from each model section, with the emissions associated with each management practice or treatment
"machinery": { "byMachineTypeAndFuel": [ { "key": { "year": 1, "machineryUseIndex": 1, "machineryType": "Baler", "fuelType": "diesel (100% mineral diesel)", "label": "machine 1" }, "value": { "CO2eq": 4599.896 } }, { "key": { "year": 1, "machineryUseIndex": 2, "machineryType": "Chopping wine wood", "fuelType": "biodiesel HVO", "label": "Machine 2 " }, "value": { "CO2eq": 8324.12
Result Aggregations
Compiles results into meaningful aggregations for example, the top-level view of emissions for model categories broken out by GHGs
Or
Results compiled into FLAG categories (coming soon)
Input Validation Report
User input -
This section will provide details of any input errors that have been detected in your API call, and often some helpful advice on how you can fix it
inputDataValidationReport": { "userInput": { "SOC": [], "nonCrop": [], "residue": [ { "type": "enum", "field": "residue.residueManagementPractice", "input": "eating", "message": "Input should be 'burning', 'left_in_heaps_or_pits', 'composting_forced_aeration', 'composting_non_forced_aeration', 'left_on_field', 'exporting' or 'chipping_and_spreading'" } ], "machinery": [], "pesticide": [], "transport": [], "fertiliser": [], "fuelEnergy": [], "irrigation": [], "wasteWater": [], "cropDetails": [], "refrigerants": [], "seedProduction": [], "nonCropMeasured": [], "landUseChangeBiomass": [] },
Model Input
Provides information on any errors generated by the model calculations
Assessment meta data
Provides useful data about the assessment including the associated farm data. see the example below
- { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "createdAt": "2025-06-20T16:14:51.604Z", "updatedAt": "2025-06-20T16:14:51.604Z", "name": "string", "farmId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "purposes": [ "Testing" ], "createdBy": "user@example.com", "status": "Not started", "farm": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "createdAt": "2025-06-20T16:14:51.604Z", "updatedAt": "2025-06-20T16:14:51.604Z", "name": "Example Farm", "farmIdentifier": "Example identifier", "country": "United Kingdom of Great Britain and Northern Ireland", "latitude": 51.28, "longitude": 0.52, "climate": "Cool Temperate Moist", "soilCharacteristic": "High activity clay", "annualAverageTemperature": { "value": 10, "unit": "°C" }, "owner": "user@example.com" },
Old runs summary
If the assessment has been upgraded from a previous version of CF you can see details bou that in this section
Aggregation Groups
Related Articles
Cool Farm Tool User Guide-Crops
Find attached our Cool Farm Tool User Guide for Crops. (please note these are due to be updated shortly)Cool Farm Tool User Guide- Livestock (Beef & Dairy)
Find attached our Cool Farm Tool User Guide for Livestock (Beef & Dairy).I am interested in connecting my software to the CFT via API. What is needed for that?
Ensure you are reading the guidance for the correct Tool. We have guidance that varies based on whether you are using the CFT or CFP, outlined below. Cool Farm Tool In the https://app.coolfarmtool.org/ at the end of the page you can find the API ...Cool Farm Platform - Quick Start Guide
Welcome to the Cool Farm Platform! This Quick Start Guide will walk you through the registration process and help you take your first steps with the Cool Farm Platform (CFP). Registration Go to https://cfp.coolfarm.org/. Click on Sign in. If you ...Cool Farm Platform - Sharing and Aggregation Guide
Beta Phase As of the June CFP 3.0 release, Sharing and Aggregation is available to all permissioned members as a beta feature. During this phase, we encourage members to trial the feature extensively and provide as much feedback as possible. Your ...