{
  "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 magic email link 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 magic claim link. Agents can optionally include onboarding answers, writing samples, and Markdown documents. Clarus stores that setup encrypted, returns a limited free writing-profile preview plus a status token for polling, and applies the setup only after the human claims the account. 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."
                  },
                  "agentSetup": {
                    "type": "object",
                    "additionalProperties": false,
                    "description": "Optional setup data the agent collected from the human. Clarus stores this on the pending intent and applies it only after the human claims by email.",
                    "properties": {
                      "onboardingProfile": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "writingContext"
                        ],
                        "properties": {
                          "writingContext": {
                            "type": "string",
                            "enum": [
                              "work",
                              "school",
                              "other_projects"
                            ]
                          },
                          "industry": {
                            "type": "string",
                            "enum": [
                              "marketing_communications",
                              "technology_software",
                              "sales_business_development",
                              "education_academia",
                              "legal",
                              "healthcare_medical",
                              "finance_accounting",
                              "journalism_media",
                              "creative_writing_publishing",
                              "other"
                            ],
                            "description": "Use only when writingContext is work."
                          },
                          "useCase": {
                            "type": "string",
                            "enum": [
                              "bloggers",
                              "founders",
                              "newsletter_writers",
                              "marketers",
                              "technical_writers",
                              "academics_researchers",
                              "managers_leaders",
                              "freelance_writers",
                              "students",
                              "journalers_personal_writers"
                            ],
                            "description": "Required when writingContext is work and industry is other."
                          },
                          "role": {
                            "type": "string",
                            "enum": [
                              "individual_contributor",
                              "manager",
                              "director",
                              "executive_owner",
                              "student",
                              "freelancer_consultant",
                              "other"
                            ],
                            "description": "Use only when writingContext is work."
                          },
                          "schoolStage": {
                            "type": "string",
                            "enum": [
                              "high_school",
                              "college",
                              "graduate",
                              "other"
                            ],
                            "description": "Use only when writingContext is school."
                          },
                          "graduationTerm": {
                            "type": "string",
                            "maxLength": 80,
                            "description": "Use only when writingContext is school."
                          },
                          "projectWritingType": {
                            "type": "string",
                            "enum": [
                              "email_messages",
                              "stories_creative_projects",
                              "articles_blog_posts",
                              "social_media_posts",
                              "other"
                            ],
                            "description": "Use only when writingContext is other_projects."
                          },
                          "proUpsellDisposition": {
                            "type": "string",
                            "enum": [
                              "accepted",
                              "declined"
                            ],
                            "default": "declined"
                          }
                        }
                      },
                      "writingProfile": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "sourceOwnershipAccepted",
                          "sources"
                        ],
                        "properties": {
                          "sourceOwnershipAccepted": {
                            "type": "boolean",
                            "const": true,
                            "description": "Set true only after the human confirms they own or have permission to analyze these writing samples."
                          },
                          "sources": {
                            "type": "array",
                            "minItems": 1,
                            "maxItems": 3,
                            "items": {
                              "type": "object",
                              "additionalProperties": false,
                              "required": [
                                "label",
                                "text"
                              ],
                              "properties": {
                                "kind": {
                                  "type": "string",
                                  "enum": [
                                    "paste",
                                    "upload",
                                    "doc",
                                    "url"
                                  ],
                                  "default": "paste"
                                },
                                "label": {
                                  "type": "string",
                                  "maxLength": 160
                                },
                                "text": {
                                  "type": "string",
                                  "maxLength": 40000,
                                  "description": "Plain text writing sample. Do not send private material unless the human explicitly provided it for profile generation."
                                },
                                "category": {
                                  "type": "string",
                                  "enum": [
                                    "creative_narrative",
                                    "academic_research",
                                    "business_professional",
                                    "journalism_editorial",
                                    "technical_documentation",
                                    "marketing_persuasive",
                                    "personal_informal",
                                    "organizational_communication",
                                    "general"
                                  ]
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri",
                                  "maxLength": 2048
                                },
                                "filename": {
                                  "type": "string",
                                  "maxLength": 240
                                },
                                "mimeType": {
                                  "type": "string",
                                  "maxLength": 120
                                }
                              }
                            }
                          }
                        }
                      },
                      "documentImport": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "documents"
                        ],
                        "description": "Optional Markdown documents to import into Clarus after the human claims the account. Use this only for documents the human explicitly asked the agent to import.",
                        "properties": {
                          "projectName": {
                            "type": "string",
                            "maxLength": 120,
                            "description": "Optional project name to group the imported documents."
                          },
                          "projectDescription": {
                            "type": "string",
                            "maxLength": 2000
                          },
                          "documents": {
                            "type": "array",
                            "minItems": 1,
                            "maxItems": 5,
                            "items": {
                              "type": "object",
                              "additionalProperties": false,
                              "required": [
                                "title",
                                "markdown"
                              ],
                              "properties": {
                                "title": {
                                  "type": "string",
                                  "maxLength": 160
                                },
                                "markdown": {
                                  "type": "string",
                                  "maxLength": 40000,
                                  "description": "Markdown content to create as a Clarus document after claim."
                                },
                                "docKind": {
                                  "type": "string",
                                  "enum": [
                                    "standard",
                                    "research"
                                  ],
                                  "default": "standard"
                                },
                                "frontmatter": {
                                  "type": "string",
                                  "maxLength": 8000
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "examples": {
                "basic": {
                  "value": {
                    "email": "you@example.com",
                    "agentName": "Agent CLI",
                    "requestedUse": "Set up Clarus for my writing work.",
                    "agentSetup": {
                      "onboardingProfile": {
                        "writingContext": "work",
                        "industry": "technology_software",
                        "role": "individual_contributor",
                        "proUpsellDisposition": "declined"
                      },
                      "writingProfile": {
                        "sourceOwnershipAccepted": true,
                        "sources": [
                          {
                            "kind": "paste",
                            "label": "Recent draft",
                            "text": "Paste a short writing sample collected from the human here.",
                            "category": "business_professional"
                          }
                        ]
                      },
                      "documentImport": {
                        "projectName": "Imported drafts",
                        "documents": [
                          {
                            "title": "Draft essay",
                            "markdown": "# Draft essay\n\nPaste a document the human asked the agent to import."
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "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",
                    "statusToken",
                    "statusUrl",
                    "agentStatus",
                    "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 means the address is currently rate-limited."
                    },
                    "expiresAt": {
                      "type": "number",
                      "description": "Unix epoch milliseconds for the claim intent expiration."
                    },
                    "statusToken": {
                      "type": "string",
                      "description": "Opaque token the agent can use to poll this intent. This is not the human claim token."
                    },
                    "statusPath": {
                      "type": "string",
                      "description": "Relative path for polling this intent from the same API origin."
                    },
                    "statusUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Absolute URL for polling the free writing-profile preview and setup status."
                    },
                    "agentStatus": {
                      "type": "object",
                      "description": "Current status payload. Poll the statusUrl later for the same shape.",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "claimed",
                            "expired",
                            "revoked"
                          ]
                        },
                        "setup": {
                          "type": "object",
                          "properties": {
                            "hasOnboardingProfile": {
                              "type": "boolean"
                            },
                            "writingProfileSourceCount": {
                              "type": "number"
                            },
                            "importedDocumentCount": {
                              "type": "number"
                            },
                            "importedProjectName": {
                              "type": "string"
                            },
                            "appliedAt": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          }
                        },
                        "freeWritingProfile": {
                          "type": "object",
                          "description": "Limited free profile preview. Ask the human to claim for the complete Stylogram."
                        },
                        "completeStylogram": {
                          "type": "object",
                          "properties": {
                            "availableAfterClaim": {
                              "type": "boolean"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        },
                        "proUpsell": {
                          "type": "object",
                          "description": "Prompt copy and subscribe path for Pro, which unlocks Clarus Coach feedback on imported documents."
                        },
                        "agentGuidance": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "proPrompt": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body."
          },
          "405": {
            "description": "Method not allowed."
          },
          "413": {
            "description": "Request body too large."
          }
        }
      },
      "get": {
        "operationId": "getAgentSignupIntentStatus",
        "summary": "Poll a claimable signup intent",
        "description": "Returns the pending signup status, limited free writing-profile preview, imported-document setup state, and copy the agent can use to ask the human to claim the account or upgrade to Pro for Clarus Coach feedback. Requires the statusToken returned by createAgentSignupIntent. This token is not a claim token.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The statusToken returned by createAgentSignupIntent."
          }
        ],
        "responses": {
          "200": {
            "description": "Current signup intent status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "claimed",
                        "expired",
                        "revoked"
                      ]
                    },
                    "email": {
                      "type": "string",
                      "description": "Masked email address."
                    },
                    "setup": {
                      "type": "object",
                      "properties": {
                        "hasOnboardingProfile": {
                          "type": "boolean"
                        },
                        "writingProfileSourceCount": {
                          "type": "number"
                        },
                        "importedDocumentCount": {
                          "type": "number"
                        },
                        "importedProjectName": {
                          "type": "string"
                        },
                        "appliedAt": {
                          "type": [
                            "number",
                            "null"
                          ]
                        }
                      }
                    },
                    "freeWritingProfile": {
                      "type": "object",
                      "description": "Limited preview generated from the supplied writing samples."
                    },
                    "completeStylogram": {
                      "type": "object",
                      "description": "Claim prompt for viewing the complete Stylogram."
                    },
                    "proUpsell": {
                      "type": "object",
                      "description": "Pro upgrade prompt for running Clarus Coach feedback on imported documents."
                    },
                    "agentGuidance": {
                      "type": "object",
                      "description": "Ready-to-use guidance copy for the agent to show the human."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid status token."
          },
          "404": {
            "description": "Status token not found."
          }
        }
      }
    }
  }
}