TaughtHuman decisions for better models

Ship the model your project taught.

Send one image to a promoted endpoint. Receive normalized detections, an exact model receipt, and versioned usage in one response.

Inference API · v1 contract

Canonical contract. Confirm hosted-inference availability for your deployment before calling it.

Method
POST
Path
/v1/endpoints/{slug}/predict
Body
multipart/form-data
Auth
Bearer API key
Retry safety
Idempotency-Key required
01 · Quickstart

One request, one accountable receipt.

Set YOUR_TAUGHT_HOST to the service origin provided for your deployment. The example deliberately does not assume that the marketing domain or any public API hostname is your serving origin.

Terminal · multipart image
curl --request POST \
  "$YOUR_TAUGHT_HOST/v1/endpoints/yard-dogs/predict" \
  --header "Authorization: Bearer taught_live_YOUR_API_KEY" \
  --header "Idempotency-Key: infer_0187_retry_1" \
  --form "file=@./trail-camera.jpg" \
  --form "threshold=0.45"
02 · Authentication

Keep bearer keys on the server.

Send the live API key in the standard Authorization header. Keys use the taught_live_ prefix, are secret credentials, and should never be embedded in browser or mobile-client source. The key owner must remain an active member of the endpoint’s project.

Authorization: Bearer taught_live_YOUR_API_KEYRequired on every prediction request
03 · Image request

Upload the source; choose a threshold only when needed.

file
file · requiredThe image bytes to inspect. Taught hashes and decodes the received file before inference.
threshold
number · optionalA score threshold from 0 through 1. Omit it to use the endpoint’s configured threshold.

The selected endpoint revision determines the promoted model, taxonomy, pricing rule, and serving constraints. Clients do not choose arbitrary checkpoint files.

04 · Detection response

Predictions are normalized. Provenance is not.

Box geometry uses coordinates normalized to the decoded input width and height. Every successful response also identifies the exact endpoint revision, model weights, taxonomy, input hash, accelerator, pricing version, credit charge, and request ID.

200 OK · application/json
{
  "object": "inference_result",
  "request_id": "5d0f38c0-7edf-4a77-bb74-adf0e946019b",
  "model_version_id": "mdl_01J7YMC9VH",
  "created_at": "2026-08-28T19:42:31.482Z",
  "completed_at": "2026-08-28T19:42:31.566Z",
  "endpoint": {
    "id": "end_01J7YPNF7B",
    "slug": "yard-dogs",
    "project_id": "project_01J7YJQJ7F",
    "revision_id": "rev_01J7YPV36S",
    "revision": 12
  },
  "model": {
    "id": "mdl_01J7YMC9VH",
    "provider": "rfdetr",
    "architecture": "RF-DETR Small",
    "model_size": "small",
    "task_type": "detection",
    "taxonomy_version": 7,
    "weights_sha256": "2f4d2b9dc2fa24f2f0c36f7f44bbf257cc2382d68a00f10dac10d7cd989a91aa",
    "weights_size_bytes": 385744117,
    "class_map_sha256": "eb0d85ba92bc9aabf57ea06f7f19c97bcd628b7220c327576e9be01f52d43739"
  },
  "input": {
    "media_type": "image/jpeg",
    "size_bytes": 641227,
    "width": 1920,
    "height": 1080,
    "sha256": "85de5bd97d3cb33cb56a972bc7d079eb206d49522762f6a4d64dcc2b29aa11c0"
  },
  "predictions": [
    {
      "class_id": "dog",
      "class_name": "Dog",
      "score": 0.9472,
      "geometry_kind": "box",
      "geometry": {
        "type": "box",
        "coordinate_space": "normalized",
        "x": 0.184,
        "y": 0.271,
        "width": 0.327,
        "height": 0.486
      }
    }
  ],
  "usage": {
    "credits": 3,
    "credits_charged": 3,
    "prediction_count": 1,
    "duration_ms": 84.013,
    "accelerator": { "selected": "mps", "verified": true },
    "pricing": {
      "version": "credits-v1",
      "base_credits": 0,
      "per_megapixel_credits": 1,
      "minimum_credits": 1,
      "formula": "max(minimum_credits, base_credits + ceil(input_pixels * per_megapixel_credits / 1000000))"
    }
  },
  "receipt": {
    "object": "inference_usage_receipt",
    "request_id": "5d0f38c0-7edf-4a77-bb74-adf0e946019b",
    "endpoint": {
      "id": "end_01J7YPNF7B",
      "slug": "yard-dogs",
      "project_id": "project_01J7YJQJ7F",
      "revision_id": "rev_01J7YPV36S",
      "revision": 12
    },
    "model_version_id": "mdl_01J7YMC9VH",
    "model": {
      "id": "mdl_01J7YMC9VH",
      "provider": "rfdetr",
      "architecture": "RF-DETR Small",
      "model_size": "small",
      "task_type": "detection",
      "taxonomy_version": 7,
      "weights_sha256": "2f4d2b9dc2fa24f2f0c36f7f44bbf257cc2382d68a00f10dac10d7cd989a91aa",
      "weights_size_bytes": 385744117,
      "class_map_sha256": "eb0d85ba92bc9aabf57ea06f7f19c97bcd628b7220c327576e9be01f52d43739"
    },
    "outcome": "completed",
    "credits_reserved": 3,
    "credits_charged": 3,
    "pricing": {
      "version": "credits-v1",
      "base_credits": 0,
      "per_megapixel_credits": 1,
      "minimum_credits": 1,
      "formula": "max(minimum_credits, base_credits + ceil(input_pixels * per_megapixel_credits / 1000000))"
    },
    "input": {
      "sha256": "85de5bd97d3cb33cb56a972bc7d079eb206d49522762f6a4d64dcc2b29aa11c0",
      "media_type": "image/jpeg",
      "size_bytes": 641227,
      "width": 1920,
      "height": 1080
    },
    "threshold": 0.45,
    "output_schema_version": "2026-08-28",
    "usage": {
      "predictions": 1,
      "duration_ms": 84.013,
      "accelerator": { "selected": "mps", "verified": true }
    },
    "error_code": null,
    "created_at": "2026-08-28T19:42:31.482Z",
    "completed_at": "2026-08-28T19:42:31.566Z",
    "receipt_sha256": "bada14e719ef4a3809ad72641f34cb81789f744064596f2389210604b1bb7ce7"
  }
}
x, yTop-left position as a fraction of image width and height
width, heightBox extent as a fraction of image width and height
scoreModel score for this class and geometry
05 · Idempotency

Retry without paying twice.

Idempotency-Key is required on every billable prediction request. Repeating the same key with the same file and parameters returns the original inference receipt. Reusing it for different request content returns 409.

Persist the returned request_id and receipt.receipt_sha256. They are the support and accounting references for that call.

06 · Usage & credits

Read the rate receipt from the response.

usage.credits_charged is the settled service-credit amount for this inference. usage.pricing.version identifies the rate rule, while usage.duration_ms and usage.accelerator preserve the serving measurement behind it.

  • EndpointID, slug, and immutable serving revision
  • ModelID, architecture, task, taxonomy, and weight hash
  • InputDecoded dimensions, content hash, and megapixels
  • RateCompute time, credits charged, pricing version, and accelerator
07 · Agent clients

Agents use the same accountable REST path.

A server-side agent follows this prediction contract when hosted inference is enabled for its deployment. It receives the same exact endpoint, model, input, usage, and request receipt as any other application.

REST inference
Canonical contractPOST /v1/endpoints/{slug}/predict is the first machine-access path.
Model Context Protocol
2026-07-28 · implemented, deployment-gatedThe adapter is implemented, but this deployment has not published it after acceptance testing.
Agent2Agent (A2A)
1.0 · implemented, deployment-gatedThe adapter is implemented, but this deployment has not published it after acceptance testing.
Agent Client Protocol
1.x · not applicableThis agent-client/editor protocol is relevant only if Taught deliberately ships a coding-agent product; it is not a generic inference adapter.
Agent Communication Protocol (BeeAI/IBM)
Legacy 1.0 · deprecatedRetained only as a migration boundary. New agent-to-agent integrations belong on A2A.

Do not place a Taught bearer key in a prompt, browser bundle, or untrusted tool context. Broker inference through a server boundary that can restrict the endpoint and protect the secret.

08 · Errors

Fail explicitly.

Error responses use an HTTP status that describes the boundary and include a request identifier when one was created. Do not treat a timeout or transport failure as proof that no inference occurred—retry with the same idempotency key.

401Authentication failedThe bearer token is missing, malformed, revoked, or not permitted to call this endpoint.
402Inference credit requiredThe account does not have enough usable inference credit for the priced request.
409Request conflictAn idempotency key was reused with different request bytes or parameters.
413Input too largeThe uploaded file exceeds the endpoint’s current input limit.
422Input not usableThe file, threshold, media type, or endpoint task cannot produce a valid prediction.
429Rate limitedThe key, account, endpoint, or deployment reached its request or concurrent-compute allowance.
503Endpoint unavailableThe promoted model could not be served safely at this time. Retry with backoff.
504Inference timed outThe request exceeded its serving deadline. Retry with the same idempotency key.
402 Payment Required · application/json
{
  "error": {
    "code": "insufficient_credit",
    "message": "The account has insufficient inference credit."
  },
  "request_id": "req_01J7YQ7H4K"
}
09 · Task support

Detection is the first public serving contract.

This v1 prediction route currently normalizes raster-image, bounding-box object detection. Audio events, video sequences, classification, polygons, masks, oriented boxes, and keypoints require task-specific serving contracts and are not silently converted into boxes.

A model being trainable inside Taught does not by itself make that task hostable. The endpoint must advertise a compatible promoted model and serving contract.