{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mnemom-ai/json-schema/mnemom-ai-agent-schema.json",
  "title": "Agent",
  "description": "An agent. GET /v1/agents/{id} returns one of TWO projections by authorization: an ORGANIZATION-MEMBER (owner) caller receives the full agent row (all fields below); a NON-OWNER receives a reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url). additionalProperties is left open because the owner row is the full DB row and grows as agent-settings columns are added (ADR-053 / proof / DDR); over-constraining it would 500 the endpoint on the next migration under /v1 response enforcement.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mnemom-ai-openapi.json#/components/schemas/Agent",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "id": {
      "type": "string"
    },
    "claimed": {
      "type": "boolean",
      "description": "Public projection only: whether the agent has been claimed by a user."
    },
    "avatar_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "claimed_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "Owner projection: user id that claimed the agent."
    },
    "created_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "Owner projection: user id that created the agent (provenance)."
    },
    "org_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Owner projection: the agent's org binding (ADR-062 authz boundary)."
    },
    "agent_proof_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "Owner projection: captured hash_proof of the bound key (mig 263)."
    },
    "agent_proof_captured_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "deleted_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Owner projection: soft-delete timestamp (null when live)."
    },
    "agent_hash": {
      "type": "string",
      "description": "First 16 hex chars of `SHA256(apiKey + '|' + agentName)` for named agents, or `SHA256(apiKey)` for unnamed singleton agents. The gateway computes the same value on each request and uses it as the lookup key. See [Agent Identity](https://docs.mnemom.ai/concepts/agent-identity#agent_hash--the-canonical-identity-hash)."
    },
    "user_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "email": {
      "type": [
        "string",
        "null"
      ]
    },
    "claimed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "last_seen": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Agent name (2-32 chars, alphanumeric + hyphens). Present on all list and get responses."
    },
    "containment_status": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "active",
        "paused",
        "killed",
        null
      ],
      "description": "Containment state of the agent (ADR-053)."
    },
    "key_prefix": {
      "type": [
        "string",
        "null"
      ],
      "description": "First 8 chars of the bound API key hash — useful for key-rotation debugging."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "offline"
      ]
    },
    "caller": {
      "type": "string",
      "enum": [
        "anonymous",
        "authenticated",
        "org_member"
      ],
      "description": "Self-describing caller context for THIS response. `org_member` callers receive the full owner record (all fields here); `anonymous`/`authenticated` (non-member) callers receive the reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url, caller). The differing field set is GOVERNED by this value — read it instead of inferring why a field is absent."
    },
    "public": {
      "type": "boolean",
      "description": "Identity-record visibility axis — whether the agent's IDENTITY RECORD is publicly discoverable. This is DISTINCT from reputation visibility: every registered agent's reputation is public by accountability standard (see `ReputationScore.visibility`). `public` here governs only the identity record, never the Trust Rating."
    },
    "aip_enforcement_mode": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "observe",
        "enforce",
        "nudge",
        null
      ]
    },
    "billing_account_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "groups": {
      "type": "array",
      "description": "Active groups this agent belongs to, name-ordered; `[]` when none. Present on org-fleet rows (GET /v1/orgs/{org_id}/agents). Archived groups are excluded.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "color"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "description": "Group color (hex, e.g. `#0d9488`); `null` when unset."
          }
        }
      }
    }
  }
}