{
  "openapi": "3.1.0",
  "info": {
    "title": "ReplytoSocial Agent API",
    "version": "1.0.0",
    "description": "Agent-facing endpoints only. POST /api/v1/agent/signup returns an API key once. POST /api/v1/mcp is the remote MCP (streamable-http). Nothing here posts to a social network."
  },
  "servers": [
    {
      "url": "https://replytosocial.com"
    }
  ],
  "paths": {
    "/api/v1/agent/signup": {
      "post": {
        "operationId": "agentSignup",
        "summary": "Create a free-tier agent account",
        "description": "Public, CAPTCHA-free signup. Creates a free-tier user and workspace and returns an API key in plaintext once. Store it; the server keeps only a SHA-256 hash. Pass sandbox:true to mint a flagged key whose mutating MCP tools simulate and never write, generate, or charge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "referralSource": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "sandbox": {
                    "type": "boolean",
                    "description": "If true, mint a sandbox key. Mutating MCP tools return simulated success and do not perform real side effects."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created. apiKey is shown only in this response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "apiKey",
                    "userId",
                    "workspaceId",
                    "email",
                    "sandbox"
                  ],
                  "properties": {
                    "apiKey": {
                      "type": "string"
                    },
                    "keyPreview": {
                      "type": "string"
                    },
                    "userId": {
                      "type": "string"
                    },
                    "workspaceId": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "sandbox": {
                      "type": "boolean"
                    },
                    "usage": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or request body."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "Remote MCP (streamable-http)",
        "description": "JSON-RPC MCP over streamable-http. Authenticate with the key from POST /api/v1/agent/signup. Tools are scoped to the workspace the key was issued for. draft_reply generates a draft only; mark_reply_published records that a human already posted.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC or SSE response."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from POST /api/v1/agent/signup. Sent as Authorization: Bearer <apiKey>."
      }
    }
  }
}