{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Avea Robotics API", "version": "1.0.0", "description": "Customer API for robots, episode metadata, datasets, and webhooks." }, "paths": { "/v1/api-keys": { "post": { "operationId": "post_v1_api_keys", "summary": "Create a scoped API key. The plaintext key is returned exactly once.", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "scopes", "created_by", "last_used_at", "expires_at", "revoked_at", "created_at", "key" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "last_used_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revoked_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "key": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "admin", "x-avea-entitlement": "api.access", "x-avea-meter": "api_keys.created", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "minLength": 1, "maxLength": 128, "type": "string" }, "scopes": { "minItems": 1, "uniqueItems": true, "type": "array", "items": { "anyOf": [ { "const": "robots:read", "type": "string" }, { "const": "robots:command", "type": "string" }, { "const": "data:read", "type": "string" }, { "const": "data:write", "type": "string" }, { "const": "fleet:read", "type": "string" }, { "const": "admin", "type": "string" } ] } }, "expires_at": { "format": "date-time", "type": "string" } } } } } } }, "get": { "operationId": "get_v1_api_keys", "summary": "List the organization's API keys (never the secrets).", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "api_keys" ], "properties": { "api_keys": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "scopes", "created_by", "last_used_at", "expires_at", "revoked_at", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "last_used_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revoked_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" } } } } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "admin", "x-avea-entitlement": "api.access" } }, "/v1/api-keys/{id}": { "delete": { "operationId": "delete_v1_api_keys_id", "summary": "Revoke an API key. Revocation is immediate and permanent.", "tags": [ "api-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response" } }, "x-avea-audience": "api", "x-avea-scope": "admin", "x-avea-entitlement": "api.access", "x-avea-meter": "api_keys.revoked", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/go-home": { "post": { "operationId": "post_v1_robots_id_go_home", "summary": "Send the go_home command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.go_home", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/go-to-start": { "post": { "operationId": "post_v1_robots_id_go_to_start", "summary": "Send the go_to_start command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.go_to_start", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/start-autonomous": { "post": { "operationId": "post_v1_robots_id_start_autonomous", "summary": "Send the start_autonomous command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.start_autonomous", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/stop-autonomous": { "post": { "operationId": "post_v1_robots_id_stop_autonomous", "summary": "Send the stop_autonomous command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.stop_autonomous", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/stack/start": { "post": { "operationId": "post_v1_robots_id_stack_start", "summary": "Send the stack.start command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.stack_start", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/stack/stop": { "post": { "operationId": "post_v1_robots_id_stack_stop", "summary": "Send the stack.stop command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.stack_stop", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/stack/status": { "post": { "operationId": "post_v1_robots_id_stack_status", "summary": "Send the stack.status command to a robot and wait for its result.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "api.robot_commands", "x-avea-meter": "commands.stack_status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/robots/{id}/episodes/start": { "post": { "operationId": "post_v1_robots_id_episodes_start", "summary": "Start an episode recording. Rejected with 422 when the robot does not announce native episode-command support (episodes.v1).", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.started", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string" }, "subtask_id": { "type": "string" }, "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } } }, "/v1/robots/{id}/episodes/finish": { "post": { "operationId": "post_v1_robots_id_episodes_finish", "summary": "Mark the robot's current episode as finished. Rejected with 422 when the robot does not announce native episode-command support (episodes.v1).", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.finished", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } } }, "/v1/robots/{id}/episodes/fail": { "post": { "operationId": "post_v1_robots_id_episodes_fail", "summary": "Mark the robot's current episode as failed.", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.failed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } } }, "/v1/robots/{id}/episodes/discard": { "post": { "operationId": "post_v1_robots_id_episodes_discard", "summary": "Mark the robot's current episode as discarded. Rejected with 422 when the robot does not announce native episode-command support (episodes.v1).", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "ok", "type": "string" }, "result": {} } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:command", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.discarded", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } } }, "/v1/datasets": { "post": { "operationId": "post_v1_datasets", "summary": "Create a dataset from an episode filter. Membership resolves live until the dataset is snapshotted.", "tags": [ "datasets" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "description", "filter", "snapshot_at", "episode_count", "created_by", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filter": { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, "snapshot_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "episode_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_by": { "type": "string" }, "created_at": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:write", "x-avea-entitlement": "data.metadata", "x-avea-meter": "datasets.created", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "filter" ], "properties": { "name": { "minLength": 1, "maxLength": 128, "type": "string" }, "description": { "maxLength": 4096, "type": "string" }, "filter": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } }, "get": { "operationId": "get_v1_datasets", "summary": "List datasets (keyset-paginated).", "tags": [ "datasets" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "datasets", "cursor" ], "properties": { "datasets": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "filter", "snapshot_at", "episode_count", "created_by", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filter": { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, "snapshot_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "episode_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_by": { "type": "string" }, "created_at": { "type": "string" } } } }, "cursor": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "datasets.list", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 100, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100, "type": "number" } ] } } ] } }, "/v1/datasets/{id}": { "get": { "operationId": "get_v1_datasets_id", "summary": "Fetch one dataset by id.", "tags": [ "datasets" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "description", "filter", "snapshot_at", "episode_count", "created_by", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filter": { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, "snapshot_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "episode_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_by": { "type": "string" }, "created_at": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "datasets.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/datasets/{id}/snapshot": { "post": { "operationId": "post_v1_datasets_id_snapshot", "summary": "Freeze the dataset's membership: resolve the stored filter against episodes now and pin the result. Excludes eval episodes unless the filter names an eval_id (no train-on-test by default) and discarded episodes unless the filter names an outcome. One-shot: 409 if already snapshotted.", "tags": [ "datasets" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "snapshot_at", "episode_count" ], "properties": { "id": { "type": "string" }, "snapshot_at": { "type": "string" }, "episode_count": { "type": "number" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:write", "x-avea-entitlement": "data.metadata", "x-avea-meter": "datasets.snapshotted", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/datasets/{id}/manifest": { "get": { "operationId": "get_v1_datasets_id_manifest", "summary": "The snapshotted dataset's manifest as NDJSON (application/x-ndjson): a header line ({dataset_id, name, filter, snapshot_at, episode_count}) on the first page, then one line per member episode. Continue from the x-next-cursor response header. 409 until snapshotted.", "tags": [ "datasets" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/x-ndjson": { "schema": { "description": "Newline-delimited JSON containing the dataset header and member episodes.", "type": "string" } } }, "headers": { "X-Next-Cursor": { "description": "Opaque cursor for the next page; omitted when the manifest is complete.", "schema": { "type": "string" } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "datasets.manifest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 5000, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 5000, "type": "number" } ] } } ] } }, "/v1/entitlements": { "get": { "operationId": "get_v1_entitlements", "summary": "The organization's tier, feature flags, and limits.", "tags": [ "entitlements" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "tier", "features", "limits" ], "properties": { "tier": { "type": "string" }, "features": { "type": "object", "patternProperties": { "^(.*)$": { "type": "boolean" } } }, "limits": { "type": "object", "patternProperties": { "^(.*)$": { "type": "number" } } } } } } } } }, "x-avea-audience": "api" } }, "/v1/episodes": { "get": { "operationId": "get_v1_episodes", "summary": "List episodes (keyset-paginated). Filters: robot_id, task_id, subtask_id, operator_id, outcome, control_mode, policy_version_id, eval_id, from/to (started_at), plus dotted metadata.*/annotation.* equality filters.", "tags": [ "episodes" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "episodes", "cursor" ], "properties": { "episodes": { "type": "array", "items": { "type": "object", "required": [ "id", "robot_id", "recording_session_id", "episode_seq", "session_name", "task_id", "task_name", "subtask_id", "operator_id", "operator_name", "outcome", "recorded_outcome", "control_mode", "policy_version_id", "eval_id", "started_at", "ended_at", "duration_s", "message_count", "bag_size_bytes", "bag_uri", "metadata", "annotations", "reported_at" ], "properties": { "id": { "type": "string" }, "robot_id": { "type": "string" }, "recording_session_id": { "type": "string" }, "episode_seq": { "type": "number" }, "session_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtask_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, "recorded_outcome": { "nullable": true, "anyOf": [ { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, { "type": "null" } ] }, "control_mode": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policy_version_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eval_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "string" }, "ended_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration_s": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "message_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_size_bytes": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_uri": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "annotations": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "reported_at": { "type": "string" } } } }, "cursor": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.list", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 100, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100, "type": "number" } ] } }, { "name": "robot_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "task_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subtask_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "operator_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] } }, { "name": "control_mode", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "policy_version_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "eval_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "format": "date-time", "type": "string" } } ] } }, "/v1/episodes/export": { "get": { "operationId": "get_v1_episodes_export", "summary": "Export episodes as NDJSON (application/x-ndjson), same filters as the list route. Up to `limit` rows per request (default 1000, max 5000); continue from the x-next-cursor response header.", "tags": [ "episodes" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/x-ndjson": { "schema": { "description": "Newline-delimited JSON with one episode object per line.", "type": "string" } } }, "headers": { "X-Next-Cursor": { "description": "Opaque cursor for the next page; omitted when the export is complete.", "schema": { "type": "string" } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.exported", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 5000, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 5000, "type": "number" } ] } }, { "name": "robot_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "task_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "subtask_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "operator_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] } }, { "name": "control_mode", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "policy_version_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "eval_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "format": "date-time", "type": "string" } } ] } }, "/v1/episodes/{id}": { "get": { "operationId": "get_v1_episodes_id", "summary": "Fetch one episode by id.", "tags": [ "episodes" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "robot_id", "recording_session_id", "episode_seq", "session_name", "task_id", "task_name", "subtask_id", "operator_id", "operator_name", "outcome", "recorded_outcome", "control_mode", "policy_version_id", "eval_id", "started_at", "ended_at", "duration_s", "message_count", "bag_size_bytes", "bag_uri", "metadata", "annotations", "reported_at" ], "properties": { "id": { "type": "string" }, "robot_id": { "type": "string" }, "recording_session_id": { "type": "string" }, "episode_seq": { "type": "number" }, "session_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtask_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, "recorded_outcome": { "nullable": true, "anyOf": [ { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, { "type": "null" } ] }, "control_mode": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policy_version_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eval_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "string" }, "ended_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration_s": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "message_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_size_bytes": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_uri": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "annotations": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "reported_at": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_v1_episodes_id", "summary": "Shallow-merge into the episode's annotations (a null value deletes that key). Annotations only \u2014 recorded facts are immutable.", "tags": [ "episodes" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "robot_id", "recording_session_id", "episode_seq", "session_name", "task_id", "task_name", "subtask_id", "operator_id", "operator_name", "outcome", "recorded_outcome", "control_mode", "policy_version_id", "eval_id", "started_at", "ended_at", "duration_s", "message_count", "bag_size_bytes", "bag_uri", "metadata", "annotations", "reported_at" ], "properties": { "id": { "type": "string" }, "robot_id": { "type": "string" }, "recording_session_id": { "type": "string" }, "episode_seq": { "type": "number" }, "session_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtask_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, "recorded_outcome": { "nullable": true, "anyOf": [ { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, { "type": "null" } ] }, "control_mode": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policy_version_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eval_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "string" }, "ended_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration_s": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "message_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_size_bytes": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_uri": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "annotations": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "reported_at": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:write", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.annotated", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "annotations" ], "properties": { "annotations": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } } }, "/v1/episodes/{id}/segments": { "get": { "operationId": "get_v1_episodes_id_segments", "summary": "The episode's ordered subtask timeline (segments the operator stepped through).", "tags": [ "episodes" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "segments" ], "properties": { "segments": { "type": "array", "items": { "type": "object", "required": [ "segment_index", "subtask_id", "subtask_name", "subtask_order_index", "start_offset_s", "end_offset_s", "started_at", "ended_at" ], "properties": { "segment_index": { "type": "number" }, "subtask_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtask_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtask_order_index": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "start_offset_s": { "type": "number" }, "end_offset_s": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "started_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ended_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:read", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.segments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/episodes/{id}/outcome": { "patch": { "operationId": "patch_v1_episodes_id_outcome", "summary": "Change the episode's effective outcome. Every transition appends to the outcome_events audit log; recorded_outcome never changes.", "tags": [ "episodes" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "robot_id", "recording_session_id", "episode_seq", "session_name", "task_id", "task_name", "subtask_id", "operator_id", "operator_name", "outcome", "recorded_outcome", "control_mode", "policy_version_id", "eval_id", "started_at", "ended_at", "duration_s", "message_count", "bag_size_bytes", "bag_uri", "metadata", "annotations", "reported_at" ], "properties": { "id": { "type": "string" }, "robot_id": { "type": "string" }, "recording_session_id": { "type": "string" }, "episode_seq": { "type": "number" }, "session_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "task_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtask_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator_name": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, "recorded_outcome": { "nullable": true, "anyOf": [ { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, { "type": "null" } ] }, "control_mode": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policy_version_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eval_id": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "string" }, "ended_at": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration_s": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "message_count": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_size_bytes": { "nullable": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bag_uri": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "annotations": { "nullable": true, "anyOf": [ {}, { "type": "null" } ] }, "reported_at": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "data:write", "x-avea-entitlement": "data.metadata", "x-avea-meter": "episodes.outcome_changed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "discarded", "type": "string" } ] }, "reason": { "maxLength": 2048, "type": "string" } } } } } } } }, "/v1/robots": { "get": { "operationId": "get_v1_robots", "summary": "List robots in the organization (keyset-paginated).", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "robots", "cursor" ], "properties": { "robots": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "session_name", "active", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "session_name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" } } } }, "cursor": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:read", "x-avea-meter": "robots.list", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 100, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100, "type": "number" } ] } } ] } }, "/v1/robots/{id}": { "get": { "operationId": "get_v1_robots_id", "summary": "Fetch one robot by id (canonical) or session_name (convenience).", "tags": [ "robots" ], "security": [ { "bearerAuth": [] } ], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "session_name", "active", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "session_name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } }, "x-avea-audience": "api", "x-avea-scope": "robots:read", "x-avea-meter": "robots.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/meta/health": { "get": { "operationId": "get_v1_meta_health", "summary": "Check whether the customer API process is healthy.", "tags": [ "meta" ], "security": [], "responses": { "default": { "$ref": "#/components/responses/ApiError" }, "2XX": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true, "type": "boolean" } } } } } } }, "x-avea-audience": "api" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An Avea API key (`ak_...`) or an authenticated session bearer token." } }, "schemas": { "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "ApiError": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }