AgentListItem

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bithuman-ai/json-schema/bithuman-ai-agent-list-item-schema.json",
  "title": "AgentListItem",
  "description": "One agent as `GET /v1/agents` returns it — a summary, not the full record. Every field below is present on every item; the detail fields (`system_prompt`, `progress`, `model_url`, the media URLs, …) are **not** part of this shape, so read them from `GET /v1/agent/{code}` instead of expecting them here.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bithuman-ai-openapi.yaml#/components/schemas/AgentListItem",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "agent_id": {
      "type": "string",
      "description": "The same value as `code`."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Generated display name; `null` before the persona step and for deleted agents."
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "gender": {
      "type": [
        "string",
        "null"
      ]
    },
    "language": {
      "type": [
        "string",
        "null"
      ]
    },
    "image_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Portrait URL."
    },
    "thumbnail_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Thumbnail URL for the portrait."
    },
    "status": {
      "type": "string",
      "description": "Generation state — `processing`, `generating`, `completed`, `success`, `ready`, `failed` — or `deleted` for an agent you deleted, or `unknown`. **Deleted agents stay in this listing**; filter them out with `?status=ready` or on the field."
    },
    "supported_models": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Model families this agent can be launched as right now; `[]` while it is still generating."
    },
    "model_status": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/ModelStatusEntry"
      },
      "description": "Readiness per model family; `{}` while the agent is still generating."
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "ModelStatusEntry": {
      "type": "object",
      "description": "Per-family readiness for one of the agent's models.",
      "properties": {
        "state": {
          "type": "string",
          "description": "`ready` when the agent can be launched as this family, `pending` while it is still being prepared."
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why the family is not ready yet; `null` once it is."
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When this family last changed state. `null` for a family that was available from the agent's creation and never transitioned."
        },
        "planes": {
          "type": "object",
          "description": "Readiness for each place the agent runs, present only on the `essence-2` entry of an Essence 2 agent on the current engine. Absent (never `null`) for every other agent and model. `cloud` is the agent's state in the bitHuman cloud; `device` is the state of the copy for your own devices (the Swift, Android and Python SDKs, the CLI and the browser's `render=local`).",
          "properties": {
            "cloud": {
              "type": "string",
              "enum": [
                "pending",
                "ready",
                "failed"
              ],
              "description": "The agent's state in the bitHuman cloud; the same value as `state`."
            },
            "device": {
              "type": "string",
              "enum": [
                "absent",
                "preparing",
                "ready",
                "failed"
              ],
              "description": "`absent` not built yet; `preparing` requested or building; `ready` built and downloadable; `failed` the build stopped."
            }
          }
        }
      }
    }
  }
}