# Machine Vision Cloud

> The cloud for vision AI agents. An agent is a visual worker you define with
> one natural-language instruction: it sees (nine skills, from defect inspection
> to text-prompted segmentation), learns your standards from labeled example
> images (no retraining), proves its accuracy with evals, and acts on what it
> finds (signed webhooks, a human review queue, an unattended inbox). POST an
> image, get structured JSON back: verdicts, bounding boxes (pixels, origin
> top-left, in the submitted image's own resolution), classes, text,
> polygon segments.

Base URL: https://api.machinevision.cloud
Path convention: `/agents/...` is canonical; `/tasks/...` is a permanent alias
for the exact same routes and will never break. Payload field names (task_id,
task_type, ...) are unchanged.
Auth: `Authorization: Bearer <mvc_live_... or mvc_test_...>` (create keys in the
console at https://machinevision.cloud, or fully machine-to-machine — see below).
`mvc_test_` sandbox keys are free forever and return deterministic mock results
with the exact production schema — build and test your integration end-to-end
before spending anything.
Pricing — monitoring is per source, per month (subscription accrues daily,
prorated; includes observations, then metered overage at the agent's tier
price): camera $5/mo (1,500 observations included) · satellite AOI $10/mo
(daily imagery included) · capture endpoint $20/mo (500 captures included).
There is no free plan: live inspections and sources require a payment
method on file. Nothing is charged mid-month — on the 1st the previous
month's accrual is invoiced through Stripe and charged automatically to
the card on file (totals under $0.50 roll forward). Build and test free forever with mvc_test_ sandbox keys
(deterministic mock results, exact production schema); card-less tenants
also get a few REAL inferences per month on the platform's own demo images
(https://machinevision.cloud/demo/... — the response reports
usage.demo_runs_remaining). Direct API
calls meter per inspection: speed $0.002 · balanced $0.01 (default) ·
precision $0.04 · segmentation $0.01 · generation $0.05/image. Teaching
examples attached to a call bill $0.002 each (`items_used` in the response);
every response reports its exact `usage.cost_usd`. Camera/high-volume agents
should route to the speed tier (inference_config.tier).

Machine-to-machine onboarding (no console, for coding agents): sign in with
email/password via Google Identity Toolkit —
POST https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=AIzaSyBaAGDzJZ39lFUmh5OFlD7GUM5M_72REKo
(or accounts:signInWithPassword for an existing account) with
{"email","password","returnSecureToken":true}; use the returned idToken as the
Bearer token; call POST /me/bootstrap once (first call provisions your
workspace). IMPORTANT: after the first bootstrap, mint a FRESH idToken
(accounts:signInWithPassword again, or POST
https://securetoken.googleapis.com/v1/token?key=<same key> with
{"grant_type":"refresh_token","refresh_token":<refreshToken>}) — the old
token predates your tenant claim and gets 403 TENANT_NOT_PROVISIONED.
Then mint a durable key with POST /api-keys
{"name":"my-agent","type":"live"} — the secret is shown once.

Webhook payload (actions): POST JSON {event: "inspection.completed", trigger,
timestamp, task_id, task_name, request_id, verdict, result, image_url, source}
signed with X-MVC-Signature = "sha256=" + HMAC_SHA256(secret,
"{X-MVC-Timestamp}.{raw_body}") — verify with a constant-time compare and
reject stale timestamps.

## Quickstart

1. Create an agent (one natural-language instruction defines its job):
   POST /agents
   {"name": "damage_check", "task_type": "visual_inspection",
    "instruction": "Inspect the returned item for scratches, dents, or cracks."}
2. Put it to work:
   POST /agents/{task_id}/inspect
   {"image_url": "https://example.com/photo.jpg"}
   -> {"result": {"verdict": "FAIL", "defects": [{"class": "scratch",
      "bounding_box": {...}, "confidence": 0.93, ...}]}, "usage": {...}}
3. Teach it your standards: create a visual context (POST /contexts), add
   labeled reference images (POST /contexts/{id}/items), and point the agent at
   it (PATCH /agents/{id} inference_config.context_id). No training pipeline.
4. Let it act: give the agent "actions" — HMAC-signed webhooks, or
   {"type": "email", "to": ["ops@you.com"]} alerts for humans — on FAIL,
   on review-flagged results, on "failure" (an unattended submission
   errored), or always — and a "review" policy so uncertain calls wait for a
   human; corrections can be saved back as training examples in one call.

Skills (task_type): visual_inspection, anomaly_detection, object_detection,
segmentation, classification, ocr, visual_qa, plus experimental pose_estimation
and measurement. Send `Idempotency-Key` headers on inspections, inbox
submissions, and source creation to make retries safe (replays return
`Idempotency-Replayed: true`). Errors use {"error": {"code", "message"}} with stable codes.
Rate limits: 60 requests/minute per tenant on the default "Prototype" plan — check
GET /settings/rate-limits (readable with your API key); 429 responses carry
Retry-After. Webhook actions retry 3 times with backoff; inspect delivery
attempts at GET /agents/{id}/deliveries.

## Sources (where images come from)

An agent can watch registered sources: POST /sources with kind
"capture_endpoint" (returns a public white-label phone-capture URL — a
tenant-branded client at machinevision.cloud/capture/{token}, upload-only,
revocable), "camera" (push: point the NVR webhook at the agent inbox with
source.source_id = the source_key; or pull: set camera.snapshot_url +
snapshot_interval_minutes (min 5; polls run on a 5-minute scheduler, so
cadence is honored within ~5 min) and the platform polls a still frame —
public addresses only), or "satellite_aoi" (satellite.bbox = [west, south, east,
north]; the platform pulls the newest daily imagery over the area, skips
fully overcast passes unbilled, and auto-establishes a cloud-screened
baseline reference example on the first clear pass). GET
/sources/{id}/observations is the source's timeline; sources report derived
health ("waiting" | "watching" | "ok" | "silent" vs their expected
cadence), last_polled_at, and last_poll_error.

## Key endpoints

- [OpenAPI document](https://api.machinevision.cloud/openapi.json): the complete,
  generated contract - request/response schemas for every endpoint (paths are
  listed under the /tasks alias; substitute /agents freely)
- POST /agents, GET /agents, PATCH /agents/{id}: define and manage agents
- POST /agents/{id}/inspect: run one image (JSON image_url or multipart upload)
- POST /agents/{id}/inspect/batch: run up to 1000 images asynchronously
- POST /agents/{id}/inbox: queue one image for unattended work (202; results
  flow to webhooks and the review queue; accepts source metadata like a camera id)
- Agent automation fields: "actions" (up to 5; type webhook — HMAC-signed —
  or email; triggers always | verdict_fail | review_flagged | failure) and
  "review" (escalate FAIL or low-confidence results to humans).
  POST /agents/{id}/actions appends or updates ONE action without touching
  the rest; PATCH /agents/{id} with "actions" replaces the whole list.
  DELETE /agents/{id} refuses (409 TASK_HAS_SOURCES) while sources are
  attached — delete or reassign them first
- GET /reviews, POST /reviews/{id}/approve | /override | /example: the human
  review queue; /example saves the corrected image as a labeled training example
  — the agent learns from every correction
- GET /templates, POST /templates/{id}/tasks: ready-made agents you can hire
- POST /contexts, POST /contexts/{id}/items: training examples (visual context)
- GET /usage: monthly usage, spend, and source subscriptions
- GET /attention: what needs a human now — waiting reviews, silent sources,
  failing pulls, cloudy-AOI streaks, recent FAIL verdicts (the console Home);
  POST /attention/ack {kind, ref} dismisses one item; PATCH /sources/{id}
  {"muted": true} silences a source's feed items
- GET|PATCH /settings/notifications: daily digest email of the attention
  feed ({digest_enabled, digest_emails, digest_hour_utc})
- GET /health: liveness

## Python SDK

pip install machinevision-cloud — `machinevision.Client(api_key=...)` wraps
the full surface: agents, inspect, batch, inbox, reviews, contexts,
sources (create_source/list_source_observations/...), actions
(add_action for webhooks AND email alerts), attention, usage.

## MCP

Remote MCP server (streamable HTTP, stateless): https://api.machinevision.cloud/mcp
Authenticate with the same Bearer API key. Your coding agent can create, teach,
evaluate, and run vision agents by itself — including the acting surface:
webhooks, reviews, the inbox. Tools: list_templates, create_task_from_template,
create_task, list_tasks, get_task, inspect_image, list_contexts,
add_context_item, get_usage, create_eval_set, add_eval_item, evaluate_task,
get_evaluation, generate_context_items, get_generation, set_webhook_action,
set_review_policy, list_reviews, resolve_review, save_review_example,
list_deliveries, submit_to_inbox, list_inbox, create_source, list_sources,
get_source, list_source_observations, delete_source, delete_task,
set_email_alert (tool names keep the task noun for compatibility).

## Docs

This file plus [openapi.json](https://api.machinevision.cloud/openapi.json)
are the complete anonymous-access contract. The console docs below require
sign-in (free account):
- [Console & quickstart](https://machinevision.cloud/docs) (sign-in required)
- [API reference](https://machinevision.cloud/docs/api) (sign-in required)