soilsidekick

SoilSidekick - the Ruby gem for the SoilSidekick Pro API

Agricultural intelligence and soil analysis API with tier-based access control.

What's New in 1.2.0

  • Consumer Plant Care APIs: Three new endpoints addressing top pain points in plant ID apps:
    • /safe-identification: Toxic lookalike warnings and environmental context
    • /dynamic-care: Hyper-localized, real-time care recommendations
    • /beginner-guidance: Judgment-free, jargon-free plant guidance

Authentication

All endpoints require an API key passed via the x-api-key header:

x-api-key: ak_your_api_key_here

API keys are generated through the dashboard and use the ak_* format.

Rate Limiting

Rate limits are enforced based on your subscription tier:

  • Free: 10 req/min, 100 req/hour, 1,000 req/day
  • Starter: 30 req/min, 500 req/hour, 5,000 req/day
  • Pro: 100 req/min, 2,000 req/hour, 25,000 req/day
  • Enterprise: 500 req/min, 10,000 req/hour, 100,000 req/day

Rate limit information is returned in response headers:

  • X-RateLimit-Limit: Maximum requests in window
  • X-RateLimit-Remaining: Remaining requests in window
  • X-RateLimit-Reset: Unix timestamp when limit resets

Response Time SLAs

All endpoints return response time headers for performance monitoring:

  • X-Response-Time: Human-readable response time (e.g., \"245ms\")
  • X-Response-Time-Ms: Response time in milliseconds
  • X-Response-Time-Target: Target response time for this endpoint
  • X-Response-Time-Max: Maximum acceptable response time
  • X-Response-Time-Status: Performance status (optimal, acceptable, exceeded)

Response Time Targets by Category

Category Target Maximum Endpoints
Fast 200ms 500ms county-lookup, check-subscription
Standard 500ms 1,500ms get-soil-data, territorial-water-quality
Complex 2,000ms 5,000ms agricultural-intelligence, gpt5-chat, visual-crop-analysis
Heavy 5,000ms 15,000ms live-agricultural-data, generate-vrt-prescription

This SDK is automatically generated by the OpenAPI Generator project:

  • API version: 3.0.0
  • Package version: 3.0.0
  • Generator version: 7.23.0
  • Build package: org.openapitools.codegen.languages.RubyClientCodegen For more information, please visit https://soilsidekick.com/support

Installation

Build a gem

To build the Ruby code into a gem:

gem build soilsidekick.gemspec

Then either install the gem locally:

gem install ./soilsidekick-3.0.0.gem

(for development, run gem install --dev ./soilsidekick-3.0.0.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'soilsidekick', '~> 3.0.0'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/GIT_USER_ID/GIT_REPO_ID, then add the following in the Gemfile:

gem 'soilsidekick', :git => 'https://github.com/GIT_USER_ID/GIT_REPO_ID.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'soilsidekick'

# Setup authorization
SoilSidekick.configure do |config|
  # Configure API key authorization: ApiKeyAuth
  config.api_key['x-api-key'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  # config.api_key_prefix['x-api-key'] = 'Bearer'
end

api_instance = SoilSidekick::AIServicesApi.new
generate_smart_report_summary_request = SoilSidekick::GenerateSmartReportSummaryRequest.new({report_type: 'soil', report_data: 3.56}) # GenerateSmartReportSummaryRequest | 
opts = {
  x_tq_context_mode: 4096, # Integer | TurboQuant extended context window size (tokens). With 3-bit KV cache, context windows up to 24K tokens are feasible within the same memory budget as standard 4K. 
  x_tq_kv_cache_hint: 'none', # String | KV cache management hint. - `none`: No caching (default) - `reuse`: Reuse KV cache from previous request in same session (40-60% compute savings) - `persist`: Persist cache to disk for cross-session reuse 
  x_tq_model_tier: 'auto' # String | Preferred model tier for inference. - `auto`: Server selects optimal model based on device capabilities - `gemma-2b`: Lightweight model (~0.5GB KV with TQ) - `gemma-7b`: Full model, standard KV cache - `gemma-7b-tq`: Full model with TurboQuant 3-bit KV cache (~1.3GB) 
}

begin
  #Generate AI report summary
  result = api_instance.generate_smart_report_summary(generate_smart_report_summary_request, opts)
  p result
rescue SoilSidekick::ApiError => e
  puts "Exception when calling AIServicesApi->generate_smart_report_summary: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://wzgnxkoeqzvueypwzvyn.supabase.co/functions/v1

Class Method HTTP request Description
SoilSidekick::AIServicesApi generate_smart_report_summary POST /smart-report-summary Generate AI report summary
SoilSidekick::AIServicesApi get_agricultural_intelligence POST /agricultural-intelligence Get AI-powered agricultural insights
SoilSidekick::AIServicesApi get_seasonal_planning_assistant POST /seasonal-planning-assistant Get seasonal planning recommendations
SoilSidekick::AIServicesApi visual_crop_analysis POST /visual-crop-analysis Analyze crop images
SoilSidekick::CarbonApi calculate_carbon_credits POST /carbon-credit-calculator Calculate carbon credits
SoilSidekick::ConsumerPlantCareApi beginner_guidance POST /beginner-guidance Beginner-friendly plant guidance without jargon
SoilSidekick::ConsumerPlantCareApi dynamic_care POST /dynamic-care Hyper-localized dynamic plant care recommendations
SoilSidekick::ConsumerPlantCareApi safe_identification POST /safe-identification Safe plant identification with toxic lookalike warnings
SoilSidekick::EnvironmentalApi calculate_environmental_impact POST /environmental-impact-engine Calculate environmental impact
SoilSidekick::GeographicApi county_lookup POST /county-lookup Search for counties
SoilSidekick::LeafEnginesApi leafengines_query POST /leafengines-query Query plant-environment compatibility
SoilSidekick::SatelliteDataApi get_satellite_data POST /alpha-earth-environmental-enhancement Get satellite environmental data
SoilSidekick::SoilAnalysisApi get_live_agricultural_data POST /live-agricultural-data Get live agricultural data
SoilSidekick::SoilAnalysisApi get_planting_calendar POST /multi-parameter-planting-calendar Get planting calendar recommendations
SoilSidekick::SoilAnalysisApi get_soil_data POST /get-soil-data Get soil analysis data
SoilSidekick::TurboQuantApi turbo_quant_capabilities POST /turbo-quant-capabilities Query TurboQuant device capabilities
SoilSidekick::VRTApi generate_vrt_prescription POST /generate-vrt-prescription Generate VRT prescription map
SoilSidekick::WaterQualityApi get_territorial_water_analytics POST /territorial-water-analytics Get territorial water analytics
SoilSidekick::WaterQualityApi get_water_quality POST /territorial-water-quality Get water quality data

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

ApiKeyAuth

  • Type: API key
  • API key parameter name: x-api-key
  • Location: HTTP header