{
  "openapi": "3.1.0",
  "info": {
    "title": "Clarus Agent Setup API",
    "version": "0.1.0",
    "description": "Public API for agents to create claimable Clarus signup intents. The human must claim by email before any account is active."
  },
  "servers": [
    {
      "url": "https://app.clarus.page",
      "description": "Clarus web app"
    }
  ],
  "paths": {
    "/api/agent-signup-intents": {
      "post": {
        "operationId": "createAgentSignupIntent",
        "summary": "Create a claimable signup intent",
        "description": "Creates or refreshes a pending signup intent for a human email address. Clarus emails the human a claim link. The response never includes the claim token.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "additionalProperties": false,
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Human email address that will receive the claim link."
                  },
                  "humanName": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Optional human-readable name for the intended account owner."
                  },
                  "agentName": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Name of the agent or agent CLI making the request."
                  },
                  "agentUrl": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 500,
                    "description": "Optional HTTPS URL identifying the agent."
                  },
                  "requestedUse": {
                    "type": "string",
                    "maxLength": 280,
                    "description": "Short explanation shown to the human in the claim email."
                  }
                }
              },
              "examples": {
                "basic": {
                  "value": {
                    "email": "you@example.com",
                    "agentName": "Agent CLI",
                    "requestedUse": "Set up Clarus for my writing work."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. If the address can receive Clarus email, a claim link will be sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "email",
                    "emailSent",
                    "expiresAt",
                    "message"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "accepted"
                    },
                    "email": {
                      "type": "string",
                      "description": "Masked email address."
                    },
                    "emailSent": {
                      "type": "boolean",
                      "description": "Whether this request queued a new email. False can mean a recent claim email already exists."
                    },
                    "expiresAt": {
                      "type": "number",
                      "description": "Unix epoch milliseconds for the claim intent expiration."
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body."
          },
          "405": {
            "description": "Method not allowed."
          },
          "413": {
            "description": "Request body too large."
          }
        }
      }
    }
  }
}