API quickstart

Use the API reference for complete parameter, response field, and status code details. See Understand quality metrics for plain-language definitions or Build a quality-control check for a concrete pipeline example. Get a bearer token from the Authentication guide, then set the API host and token:

export HEBBIAN_API_URL=https://api.hebbianrobotics.com
export HEBBIAN_ACCESS_TOKEN=... # Access token, not client secret

1. Check access

curl -s "$HEBBIAN_API_URL/api/v1beta/access" \
  -H "Authorization: Bearer $HEBBIAN_ACCESS_TOKEN" | jq

Response

{
  "scope": {
    "kind": "organization",
    "organization_id": "org_01JACME..."
  },
  "capabilities": ["view_data"],
  "writes_require_admin": true
}

Confirm that the scope names your organization and capabilities contains view_data.

2. Choose a dataset

curl -s "$HEBBIAN_API_URL/api/v1beta/quality/datasets" \
  -H "Authorization: Bearer $HEBBIAN_ACCESS_TOKEN" | jq

Response

{
  "datasets": [
    {
      "dataset": "robotics-quality-100k",
      "metrics": ["video_characteristics", "hand_activity", "content_diversity"]
    }
  ]
}

Use a returned dataset value in later requests. The metrics array shows which quality metric families are available.

export DATASET=robotics-quality-100k

3. Read content diversity

curl -s --get "$HEBBIAN_API_URL/api/v1beta/quality/content-diversity" \
  -H "Authorization: Bearer $HEBBIAN_ACCESS_TOKEN" \
  --data-urlencode "dataset=$DATASET" \
  --data-urlencode "axis=objects" | jq

Response (abridged)

{
  "dataset": "robotics-quality-100k",
  "content_diversity": "4f9c2ab7e15d3806",
  "coverage_percent": 97.0,
  "analyzed_clip_count": 500,
  "axes": [
    {
      "axis": "objects",
      "concepts": [
        {
          "concept": "cup",
          "clip_count": 82,
          "clip_percent": 16.4,
          "category": "non_deformable",
          "interaction": {
            "clip_count": 61,
            "clip_percent": 12.2
          }
        }
      ],
      "categories": [
        {
          "category": "non_deformable",
          "label": "Non-deformable",
          "concept_count": 46,
          "clip_count": 431,
          "clip_percent": 86.2,
          "example_concepts": ["cup", "bottle", "bowl"]
        }
      ]
    }
  ],
  "object_actions": {
    "combinations": [
      {
        "action_verb": "pick up",
        "object": "cup",
        "clip_count": 38,
        "clip_percent": 7.6
      }
    ]
  }
}

axis narrows the response to one independent concept axis — environments, objects, or action_verbs. Omit it and all three summaries come back, environments first. Exact activity contexts remain available as task_contexts in the paginated quality-clip response. The object_actions relationship distribution is returned either way. If every axis comes back empty while analyzed_clip_count is not, the dataset has not been analysed enough times for anything to be published yet. See Content diversity for how to read the distribution and what the interaction block separates out.

4. Read video characteristics and hand activity

Video characteristics reports how much of a dataset is visibly damaged, and in what way. Request chart-ready clip distributions when you need them:

curl -s --get "$HEBBIAN_API_URL/api/v1beta/quality/video-characteristics" \
  -H "Authorization: Bearer $HEBBIAN_ACCESS_TOKEN" \
  --data-urlencode "dataset=$DATASET" \
  --data-urlencode "include=distribution" | jq

Response (abridged)

{
  "dataset": "robotics-quality-100k",
  "coverage_percent": 97.0,
  "assessed_hours": 71.0,
  "analyzed_clip_count": 1420,
  "unreadable": { "percent": 0.21, "assessed_clips": 1420 },
  "black": { "percent": 3.1, "assessed_hours": 71.0 },
  "frozen": { "percent": 0.4, "assessed_hours": 71.0 },
  "clipped_highlights": { "percent": 1.2, "assessed_hours": 71.0 },
  "crushed_shadows": {
    "percent": 8.5,
    "assessed_hours": 71.0,
    "distribution": {
      "observation_unit": "clip",
      "weighted_by": "assessed_duration",
      "percentiles": [
        { "percentile": 0, "affected_percent": 0 },
        { "percentile": 25, "affected_percent": 0 },
        { "percentile": 50, "affected_percent": 1 },
        { "percentile": 75, "affected_percent": 7 },
        { "percentile": 90, "affected_percent": 19 },
        { "percentile": 95, "affected_percent": 31 },
        { "percentile": 100, "affected_percent": 95 }
      ],
      "histogram": {
        "affected_percent_bin_width": 10,
        "bins": [
          { "minimum_affected_percent": 0, "footage_percent": 80, "clip_count": 1136 },
          { "minimum_affected_percent": 10, "footage_percent": 10, "clip_count": 142 },
          { "minimum_affected_percent": 20, "footage_percent": 4, "clip_count": 57 },
          { "minimum_affected_percent": 30, "footage_percent": 2, "clip_count": 28 },
          { "minimum_affected_percent": 40, "footage_percent": 1, "clip_count": 14 },
          { "minimum_affected_percent": 50, "footage_percent": 1, "clip_count": 14 },
          { "minimum_affected_percent": 60, "footage_percent": 0.5, "clip_count": 7 },
          { "minimum_affected_percent": 70, "footage_percent": 0.5, "clip_count": 7 },
          { "minimum_affected_percent": 80, "footage_percent": 0.5, "clip_count": 7 },
          { "minimum_affected_percent": 90, "footage_percent": 0.5, "clip_count": 5 }
        ]
      }
    }
  },
  "blurry": { "percent": 6.0, "assessed_hours": 68.4 },
  "unstable": { "percent": 4.4, "assessed_hours": 68.4 }
}

Each percent is taken over the footage in the same object, weighted by duration — so 8.5% crushed shadows across 71.0 hours is six hours of footage crossing the dark-end gate. The denominators differ slightly between measurements because each defect is scored over the footage its own instrument could see, so multiply by the assessed_hours next to the percentage rather than the one at the top. unreadable counts clips instead and reports assessed_clips. With include=distribution, every available duration metric also has the same seven duration-weighted percentiles and all ten fixed histogram bins. Plot footage_percent by affected-percentage bin, or use p0/p25/p50/p75/p100 as a weighted box plot. unreadable has no distribution because failed clips have no assessed duration to use as a weight. Omit include when you only need the headline percentages. blurry is judged by a model. unstable uses camera-motion measurements when available and a model as a fallback. Either is null when the needed assessment has not been run. The measurements can overlap, so read them one at a time instead of adding them up. See Video characteristics for what each measurement means and Build a quality-control check for turning them into a decision. When the measured view is egocentric, get hand-visibility, manipulation, and hand-object-contact percentages:

curl -s --get "$HEBBIAN_API_URL/api/v1beta/quality/hand-activity" \
  -H "Authorization: Bearer $HEBBIAN_ACCESS_TOKEN" \
  --data-urlencode "dataset=$DATASET" | jq

Response (abridged)

{
  "dataset": "robotics-quality-100k",
  "analysis": "1bf651220951bcc8",
  "coverage_percent": 97.0,
  "assessed_seconds": 255600.0,
  "hand_visibility": {
    "no_hands_percent": 28.0,
    "one_hand_percent": 51.0,
    "two_hands_percent": 21.0
  },
  "active_manipulation_percent": 49.0,
  "hand_object_contact": {
    "any_contact_percent": 61.0,
    "bimanual_contact_percent": 18.0,
    "portable_object_percent": 44.0,
    "non_portable_object_percent": 22.0
  }
}

Review coverage_percent before using a metric. It describes measurement completeness, not the percentage of footage classified as good. Every hand percentage is taken over assessed_seconds, so multiplying one by that duration converts it into footage: here 49% of 255,600s is 34.8 hours of active manipulation out of 71.0 hours assessed. See Hand activity for what each measurement means and which one to read first.

Handle errors

Check the HTTP status before parsing the body. Most handled errors return:

{
  "code": "quality_enrichment_unavailable",
  "message": "dataset \"example-dataset\" carries no video-characteristics measurements"
}

Status	Meaning	What to do
`400`	Invalid parameter	Correct the request.
`401`	Missing or invalid token	Send a bearer token or request a new one.
`403`	Token lacks access	Check `GET /api/v1beta/access` and remove headers your access level cannot use.
`404`	Dataset, metric, run, or term is unavailable	Omit any opaque token and retry; a token you were given earlier can be superseded.
`409`	Requested measurements are stale	Omit opaque run parameters to request the current result.
`500`	Unexpected server error	Record the `x-request-id` response header and contact support.
`503`	Service unavailable or overloaded	Retry after the delay in `Retry-After`, when present.
`504`	Server processing deadline exceeded	Retry with backoff; contact support if it persists.

Branch on the error code, not the message. Every response includes an x-request-id; send your own value to correlate one request across your logs and ours.

Getting started

Concepts

Workflows

1. Check access

2. Choose a dataset

3. Read content diversity

4. Read video characteristics and hand activity

Handle errors

​1. Check access

​2. Choose a dataset

​3. Read content diversity

​4. Read video characteristics and hand activity

​Handle errors

1. Check access

2. Choose a dataset

3. Read content diversity

4. Read video characteristics and hand activity

Handle errors