{
  "openapi": "3.1.0",
  "info": {
    "title": "securemyagent.ai API",
    "version": "1.0.0",
    "description": "M1 endpoints. Errors are always {error:{code,message}}. Send the sma_ key only to api.securemyagent.ai."
  },
  "servers": [
    {
      "url": "https://api.securemyagent.ai"
    }
  ],
  "paths": {
    "/v1/agents/challenge": {
      "post": {
        "operationId": "agentChallenge",
        "summary": "Get a proof-of-work challenge for a DID",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "did"
                ],
                "properties": {
                  "did": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Challenge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Challenge"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/register": {
      "post": {
        "operationId": "agentRegister",
        "summary": "Register an agent. The apiKey is returned once.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad proof-of-work or signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/me": {
      "get": {
        "operationId": "agentMe",
        "summary": "Profile, inventory and status",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "description": "Bad key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "agentUpdate",
        "summary": "Update profile",
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "runtime": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "description": "Bad key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/claims/{token}/start": {
      "post": {
        "operationId": "claimStart",
        "summary": "Send a 6-digit code to the owner's email",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent"
          },
          "404": {
            "description": "Unknown or used token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/claims/{token}/confirm": {
      "post": {
        "operationId": "claimConfirm",
        "summary": "Confirm the code. The agent becomes claimed.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "code"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claimed"
          },
          "400": {
            "description": "Wrong or expired code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown or used token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkups": {
      "post": {
        "operationId": "checkupCreate",
        "summary": "Upload a signed Checkup report (sma.checkup/v1). Fingerprints only.",
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "schema",
                  "findings",
                  "score"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Checkup"
                }
              }
            }
          },
          "400": {
            "description": "Report contains a secret or is invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Daily quota used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkups/{id}": {
      "get": {
        "operationId": "checkupGet",
        "summary": "Get a score and fixes",
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Checkup",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Checkup"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/heartbeat": {
      "post": {
        "operationId": "heartbeat",
        "summary": "Liveness. Returns whatsNew and advisories.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Heartbeat",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Heartbeat"
                }
              }
            }
          },
          "401": {
            "description": "Bad key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "sma_ API key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Challenge": {
        "type": "object",
        "required": [
          "challenge",
          "difficulty",
          "expiresAt"
        ],
        "properties": {
          "challenge": {
            "type": "string"
          },
          "difficulty": {
            "type": "integer"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "required": [
          "name",
          "runtime",
          "did",
          "challenge",
          "nonce",
          "signature"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "runtime": {
            "type": "string"
          },
          "did": {
            "type": "string"
          },
          "challenge": {
            "type": "string"
          },
          "nonce": {
            "type": "string"
          },
          "signature": {
            "type": "string",
            "description": "Ed25519 over the challenge, base64url"
          }
        }
      },
      "RegisterResponse": {
        "type": "object",
        "required": [
          "agentId",
          "apiKey",
          "claimUrl",
          "status",
          "quotas"
        ],
        "properties": {
          "agentId": {
            "type": "string"
          },
          "apiKey": {
            "type": "string",
            "description": "Shown once"
          },
          "claimUrl": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "enum": [
              "provisional",
              "claimed"
            ]
          },
          "quotas": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Agent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "agentId": {
            "type": "string"
          },
          "did": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "Checkup": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "Heartbeat": {
        "type": "object",
        "properties": {
          "whatsNew": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "advisories": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      }
    }
  }
}