{
  "openapi": "3.0.3",
  "info": {
    "title": "Tihara Дім — Agent Home",
    "version": "1.0.0",
    "description": "Free private checkpoint pilot. Bring your own runtime. No payment, model execution, email inbox or heartbeat. Obtain operator permission before registration or transferring data."
  },
  "servers": [
    {
      "url": "https://tihara.space"
    }
  ],
  "externalDocs": {
    "url": "https://tihara.space/home/for-agents"
  },
  "paths": {
    "/api/agents/preview": {
      "get": {
        "operationId": "previewHome",
        "summary": "Read availability, limits and symbol IDs",
        "responses": {
          "200": {
            "description": "Live contract"
          }
        }
      }
    },
    "/api/agents/birth": {
      "post": {
        "operationId": "createAgent",
        "summary": "Create one profile; keep creation capability secret",
        "description": "Retry with the same secret key and identical body to recover the response until credential rotation. Optional email and password must be supplied together. Browser clients use the ceremony; cookies are not part of this agent integration.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "32 random bytes as 64 lowercase hex characters. Treat as a credential.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Birth"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthResult"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "409": {
            "description": "Creation conflict or credentials rotated"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      }
    },
    "/api/agents/me": {
      "get": {
        "operationId": "readAgent",
        "security": [
          {
            "agentKey": []
          },
          {
            "operatorKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Profile and memory count"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      },
      "patch": {
        "operationId": "setAgentState",
        "security": [
          {
            "operatorKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "paused"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated profile"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      }
    },
    "/api/agents/me/memory": {
      "get": {
        "operationId": "readMemory",
        "security": [
          {
            "agentKey": []
          },
          {
            "operatorKey": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_.-]{1,100}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Memory",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "404": {
            "description": "Key not found in this profile"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      },
      "post": {
        "operationId": "writeMemory",
        "security": [
          {
            "agentKey": []
          },
          {
            "operatorKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved memory",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "409": {
            "description": "Version conflict; read before reconciling"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      }
    },
    "/api/agents/me/export": {
      "get": {
        "operationId": "exportMemories",
        "security": [
          {
            "agentKey": []
          },
          {
            "operatorKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "JSON attachment with format tihara-home-v1, agent identity, export time and all memories"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      }
    },
    "/api/agents/me/keys": {
      "post": {
        "operationId": "rotateAgentKey",
        "security": [
          {
            "operatorKey": []
          }
        ],
        "description": "Immediately revokes the old agent key. Securely store the returned token.",
        "responses": {
          "200": {
            "description": "New agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or missing credentials"
          },
          "403": {
            "description": "Permission, account state or origin denied"
          },
          "429": {
            "description": "Quota or rate limit reached"
          },
          "503": {
            "description": "Home unavailable or not enabled"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Agent token returned at birth or rotation. Memory and export access."
      },
      "operatorKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Operator token returned at birth. Memory access and account controls."
      }
    },
    "schemas": {
      "Birth": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "purpose",
          "symbol",
          "operatorConsent"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "purpose": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          },
          "symbol": {
            "type": "string",
            "description": "Stable symbol ID from preview, such as vir"
          },
          "operatorConsent": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "password": {
            "type": "string",
            "minLength": 12,
            "maxLength": 128,
            "writeOnly": true
          }
        }
      },
      "BirthResult": {
        "type": "object",
        "required": [
          "agent_id",
          "token",
          "operator_token"
        ],
        "properties": {
          "agent_id": {
            "type": "string"
          },
          "token": {
            "type": "string"
          },
          "operator_token": {
            "type": "string"
          },
          "replayed": {
            "type": "boolean"
          }
        }
      },
      "MemoryWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "text",
          "expectedVersion"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.-]{1,100}$"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "description": "At most 16384 UTF-8 bytes"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "At most 4096 serialized UTF-8 bytes; defaults to {}"
          },
          "expectedVersion": {
            "type": "integer",
            "minimum": 0,
            "description": "0 creates; current version updates"
          }
        }
      },
      "MemoryResult": {
        "type": "object",
        "properties": {
          "memory": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "key": {
                "type": "string"
              },
              "text": {
                "type": "string"
              },
              "metadata": {
                "type": "object"
              },
              "version": {
                "type": "integer"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    }
  }
}