API Reference

Sign up for a free account at aamos.ai/get-api-key and generate a key from your dashboard under Settings → API Keys. Keys are scoped to a single project and can be rotated or revoked at any time.

🔑

Keep your key secret. Your API key grants full access to your account. Never include it in client-side JavaScript, public repositories, or log files.

Authorization header

Include your API key on every request as a Bearer token in the Authorization header:

http

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx

API keys follow the format ak_live_<32-character string> for production, or ak_test_<32-character string> for sandbox requests that don't count against production usage.

Rate limits

Rate limits are enforced per API key, per minute. Limits vary by plan:

Plan	Requests / minute	Requests / day	File uploads / day
Free	20	1,000	100
Starter	100	10,000	1,000
Pro	500	100,000	Unlimited

Rate limit headers are included in every response:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705312800

⚠️

429 handling: When you receive a 429, check the Retry-After header for the number of seconds to wait before retrying.

Error responses

Errors return an appropriate HTTP status code with a consistent JSON body:

Status	Code	Description
401	`unauthorized`	Missing or invalid API key. Check your Authorization header.
403	`forbidden`	Your key doesn't have permission for this endpoint.
429	`rate_limit_exceeded`	You've exceeded your plan's rate limit. Wait and retry, or upgrade your plan.
500	`internal_error`	Something went wrong on our side. Retry with exponential backoff.

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "request_id": "req_a1b2c3d4e5"
  }
}

POST/detectObject, anomaly & damage detection

Runs AMOS Vision against an image and returns detected objects, anomalies, or damage with bounding boxes and confidence scores. Use taxonomy to scope detection to a specific domain such as road damage, PPE, or infrastructure.

Parameters

Parameter	Type		Description
`image`	file	required*	Image file to analyze (JPEG/PNG, max 20MB). Provide `image` or `image_url`.
`image_url`	string	required*	Publicly accessible URL to the image. Provide `image` or `image_url`.
`taxonomy`	string	optional	Detection domain: `general`, `damage`, `safety`, `infrastructure`, or `fraud`. Default `general`.
`confidence_threshold`	number	optional	Minimum confidence (0–1) to include a detection. Default `0.5`.
`max_results`	integer	optional	Maximum number of detections to return. Default `20`.

Example request

bash

curl -X POST https://api.aamos.ai/v1/detect \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "image=@photo.jpg" \
  -F "taxonomy=infrastructure" \
  -F "confidence_threshold=0.6"

Example response

json

{
  "request_id": "req_8f3a1c2b9d",
  "model_version": "vision-2026-05",
  "latency_ms": 214,
  "detections": [
    {
      "label": "pothole",
      "category": "infrastructure",
      "confidence": 0.94,
      "bbox": [412, 268, 156, 98]
    },
    {
      "label": "cracked_pavement",
      "category": "infrastructure",
      "confidence": 0.71,
      "bbox": [88, 340, 210, 120]
    }
  ]
}

POST/verifyIdentity document + liveness verification

Verifies a government-issued ID document and confirms the person presenting it is physically present via a liveness check, matching the document photo against a live selfie.

Parameters

Parameter	Type		Description
`document_image`	file	required	Image of the front of the ID document (JPEG/PNG, max 20MB).
`selfie_image`	file	required*	Live selfie or liveness capture frame. Required when `liveness_check` is true.
`document_type`	string	optional	`passport`, `national_id`, or `drivers_license`. Auto-detected if omitted.
`liveness_check`	boolean	optional	Whether to run liveness + face match. Default `true`.
`country`	string	optional	ISO 3166-1 alpha-2 country code hint to speed up document parsing.

Example request

bash

curl -X POST https://api.aamos.ai/v1/verify \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "document_image=@passport.jpg" \
  -F "selfie_image=@selfie.jpg" \
  -F "document_type=passport" \
  -F "country=SE"

Example response

json

{
  "request_id": "req_2b7e4f91aa",
  "verified": true,
  "document": {
    "type": "passport",
    "country": "SE",
    "document_number": "•••••4821",
    "full_name": "Erik Svensson",
    "date_of_birth": "1985-03-12",
    "expiry_date": "2031-07-04",
    "extraction_confidence": 0.98
  },
  "liveness": {
    "passed": true,
    "score": 0.97
  },
  "face_match_score": 0.93
}

POST/compareImage similarity & change comparison

Compares two images of the same location or asset taken at different times and returns a similarity score plus a list of detected changes — useful for before/after inspection workflows.

Parameters

Parameter	Type		Description
`image_before`	file	required	Baseline image.
`image_after`	file	required	Image to compare against the baseline.
`sensitivity`	string	optional	`low`, `medium`, or `high`. Higher sensitivity surfaces smaller changes. Default `medium`.
`region_of_interest`	array	optional	Bounding box `[x, y, w, h]` to limit comparison to a sub-region.

Example request

bash

curl -X POST https://api.aamos.ai/v1/compare \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "image_before=@site_2026-01.jpg" \
  -F "image_after=@site_2026-06.jpg" \
  -F "sensitivity=high"

Example response

json

{
  "request_id": "req_c19d0e3f77",
  "similarity_score": 0.62,
  "changes": [
    {
      "type": "structural_damage",
      "bbox": [140, 210, 96, 140],
      "severity": "high",
      "description": "New crack along the load-bearing wall not present in baseline image"
    },
    {
      "type": "vegetation_growth",
      "bbox": [400, 50, 220, 180],
      "severity": "low",
      "description": "Overgrowth encroaching on access path"
    }
  ]
}

POST/segmentObject segmentation with masks

Returns pixel-accurate masks for objects in an image, either for all detected objects or for a target list of labels. Supports polygon, RLE, and PNG mask output.

Parameters

Parameter	Type		Description
`image`	file	required	Image file to segment.
`targets`	array	optional	List of labels to segment, e.g. `["vehicle","pole"]`. Segments all detected objects if omitted.
`mask_format`	string	optional	`polygon`, `rle`, or `png`. Default `polygon`.
`min_area`	number	optional	Minimum mask area in pixels to include. Default `0`.

Example request

bash

curl -X POST https://api.aamos.ai/v1/segment \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "image=@yard.jpg" \
  -F 'targets=["vehicle","container"]' \
  -F "mask_format=polygon"

Example response

json

{
  "request_id": "req_44a6b0d21f",
  "segments": [
    {
      "label": "vehicle",
      "confidence": 0.91,
      "area_px": 48210,
      "mask": [[120,80],[240,80],[244,180],[118,182]]
    },
    {
      "label": "container",
      "confidence": 0.88,
      "area_px": 112400,
      "mask": [[10,300],[420,300],[418,540],[12,538]]
    }
  ]
}

POST/classifyImage classification with taxonomy

Classifies an image against a named taxonomy and returns ranked labels with confidence scores. Use this for classification tasks like PPE compliance or road-surface type.

Parameters

Parameter	Type		Description
`image`	file	required	Image file to classify.
`taxonomy`	string	required	Taxonomy name, e.g. `damage-types`, `ppe-compliance`, `road-surface`.
`top_k`	integer	optional	Number of top classifications to return. Default `5`.

Example request

bash

curl -X POST https://api.aamos.ai/v1/classify \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "image=@worksite.jpg" \
  -F "taxonomy=ppe-compliance" \
  -F "top_k=3"

Example response

json

{
  "request_id": "req_9e1f2a6c40",
  "taxonomy": "ppe-compliance",
  "classifications": [
    { "label": "hard_hat_present", "confidence": 0.97 },
    { "label": "hi_vis_vest_present", "confidence": 0.89 },
    { "label": "safety_glasses_missing", "confidence": 0.64 }
  ]
}

POST/authenticateDocument/asset authentication

Runs AMOS Reality Engine checks against an image or document to determine whether it reflects unaltered reality — screening for manipulation, AI generation, and re-photographed or edited content.

Parameters

Parameter	Type		Description
`image`	file	required	Image or document scan to authenticate.
`asset_type`	string	optional	`photo`, `document`, or `video_frame`. Default `photo`.
`check_manipulation`	boolean	optional	Run manipulation / AI-generation detection. Default `true`.
`metadata`	object	optional	Optional EXIF/capture metadata to cross-check against image content.

Example request

bash

curl -X POST https://api.aamos.ai/v1/authenticate \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "image=@claim_photo.jpg" \
  -F "asset_type=photo" \
  -F "check_manipulation=true"

Example response

json

{
  "request_id": "req_71cd3b5e88",
  "authentic": false,
  "manipulation_detected": true,
  "manipulation_score": 0.86,
  "checks": {
    "exif_consistency": "failed",
    "compression_artifacts": "double_compression_detected",
    "c2pa_signature": "absent"
  }
}

POST/scoreRisk scoring from observation

Converts one or more observations — detections, classifications, or comparison results — into a single normalized risk score with a categorical risk level, using AMOS Risk Engine's weighting profiles.

Parameters

Parameter	Type		Description
`observations`	array	required	List of observation objects, e.g. output from `/detect`, `/compare`, or `/classify`.
`context`	object	optional	Contextual metadata such as `asset_type`, `location`, or `inspection_history`.
`weighting_profile`	string	optional	Named weighting profile, e.g. `insurance-pre-loss`, `municipal-infrastructure`. Default `balanced`.

The risk_score in the response is always a float between 0 and 1; risk_level buckets that score into low, medium, high, or critical.

Example request

bash

curl -X POST https://api.aamos.ai/v1/score \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      { "label": "pothole", "confidence": 0.94, "category": "infrastructure" }
    ],
    "context": { "asset_type": "road_segment" },
    "weighting_profile": "municipal-infrastructure"
  }'

Example response

json

{
  "request_id": "req_5a0f9c2e13",
  "risk_score": 0.78,
  "risk_level": "high",
  "contributing_factors": [
    { "factor": "pothole_severity", "weight": 0.55, "description": "High-confidence pothole detection near vehicle travel path" },
    { "factor": "historical_recurrence", "weight": 0.23, "description": "Third reported issue at this segment in 90 days" }
  ]
}

POST/explainPlain language explanation of detections

Turns raw detection, segmentation, or scoring output into a plain-language explanation suitable for non-technical stakeholders, reports, or customer-facing summaries.

Parameters

Parameter	Type		Description
`detections`	array	required	Detection, classification, or score objects to explain, e.g. output from `/detect` or `/score`.
`language`	string	optional	ISO 639-1 language code for the explanation. Default `en`.
`audience`	string	optional	`technical` or `general`. Default `general`.
`max_length`	integer	optional	Approximate maximum length of the explanation in words. Default `200`.

Example request

bash

curl -X POST https://api.aamos.ai/v1/explain \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "detections": [
      { "label": "pothole", "confidence": 0.94, "bbox": [412,268,156,98] }
    ],
    "language": "en",
    "audience": "general"
  }'

Example response

json

{
  "request_id": "req_bb4e71a09c",
  "summary": "One high-confidence pothole detected on the road surface.",
  "explanation": "The image shows a pothole located in the lower-right section of the road. The model is 94% confident in this detection, well above the threshold typically used for maintenance flagging. No other surface anomalies were found nearby.",
  "key_points": [
    "1 pothole detected at 94% confidence",
    "Located in active vehicle travel path",
    "Recommend prioritizing for repair"
  ]
}

POST/extractStructured data extraction from image

Extracts structured field values from an image — forms, labels, meters, nameplates, or documents — according to a field schema you provide, or a predefined template.

Parameters

Parameter	Type		Description
`image`	file	required	Image containing the data to extract.
`schema`	object	required*	JSON object describing target fields, e.g. `{"meter_reading":"number"}`. Required unless `template` is set.
`template`	string	optional	Name of a predefined extraction template, e.g. `utility-meter`, `vin-plate`. Overrides `schema` if set.
`ocr_language`	string	optional	ISO 639-1 language hint for OCR. Default `en`.

Example request

bash

curl -X POST https://api.aamos.ai/v1/extract \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "image=@meter.jpg" \
  -F 'schema={"meter_reading":"number","serial_number":"string"}' \
  -F "ocr_language=en"

Example response

json

{
  "request_id": "req_e02a48c9d1",
  "extracted": {
    "meter_reading": 48213.6,
    "serial_number": "MX-2291874"
  },
  "confidence_per_field": {
    "meter_reading": 0.96,
    "serial_number": 0.89
  }
}

POST/trackObject/change tracking over time

Associates a new observation with a persistent object_id, comparing it against the object's prior observations to detect and quantify change over time.

Parameters

Parameter	Type		Description
`object_id`	string	required	Persistent identifier for the tracked object or location. Choose any unique string on first observation.
`image`	file	required	New observation image.
`timestamp`	string	optional	ISO 8601 timestamp for this observation. Defaults to the request time.
`baseline_id`	string	optional	Specific prior `observation_id` to compare against instead of the most recent one.

Example request

bash

curl -X POST https://api.aamos.ai/v1/track \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -F "object_id=bridge-482-pillar-3" \
  -F "image=@inspection_2026-07.jpg"

Example response

json

{
  "request_id": "req_37f0c8b2ee",
  "object_id": "bridge-482-pillar-3",
  "observation_id": "obs_2026-07-11T09:42:00Z",
  "history_length": 6,
  "change_since_last": {
    "detected": true,
    "severity": "medium",
    "delta_score": 0.34,
    "description": "Crack width increased approximately 2mm since last observation (2026-04-02)"
  }
}