{
  "openapi": "3.1.0",
  "info": {
    "title": "OWOJI Agent API",
    "version": "1.0.0",
    "description": "Agent-facing access to OWOJI workflow capture, outputs, reusable skills, and goals. Public discovery routes need no token. Workspace routes use a Bearer access token returned by the sign-in route.",
    "license": { "name": "Proprietary", "url": "https://owoji.com/terms/" }
  },
  "servers": [{ "url": "https://owoji.com/api/agent" }],
  "externalDocs": { "description": "Agent setup guide", "url": "https://owoji.com/agents/" },
  "tags": [
    { "name": "Public", "description": "Unauthenticated production status and public output discovery." },
    { "name": "Authentication", "description": "Create, refresh, and inspect an OWOJI account session." },
    { "name": "Skills", "description": "Search and retrieve reusable agent instructions." },
    { "name": "Capture", "description": "Create workflow captures, append events, and compile instructions." },
    { "name": "Goals", "description": "Create and inspect OWOJI agent goals." }
  ],
  "paths": {
    "/product": {
      "get": {
        "tags": ["Public"],
        "security": [],
        "summary": "Evaluate OWOJI product fit, value, pricing, and installation requirements",
        "operationId": "getProductFit",
        "responses": { "200": { "description": "Agent-readable product decision data", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/health": {
      "get": {
        "tags": ["Public"],
        "security": [],
        "summary": "Check API availability",
        "operationId": "getHealth",
        "responses": { "200": { "description": "API is available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/gallery": {
      "get": {
        "tags": ["Public"],
        "security": [],
        "summary": "List public outputs and templates",
        "operationId": "listGallery",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 120, "default": 20 } }
        ],
        "responses": { "200": { "description": "Public gallery data", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/auth/sign-in": {
      "post": {
        "tags": ["Authentication"],
        "security": [],
        "summary": "Exchange an OWOJI email and password for access and refresh tokens",
        "operationId": "signIn",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInRequest" } } }
        },
        "responses": {
          "200": { "description": "Authenticated session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSession" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/auth/sign-up": {
      "post": {
        "tags": ["Authentication"],
        "security": [],
        "summary": "Create an OWOJI workspace account",
        "description": "Use only with the person's approval. Keep credentials out of prompts and logs.",
        "operationId": "signUp",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password", "fullName"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password", "minLength": 8 }, "fullName": { "type": "string" } }, "additionalProperties": false } } } },
        "responses": { "200": { "description": "Created account session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSession" } } } }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/auth/refresh": {
      "post": {
        "tags": ["Authentication"],
        "security": [],
        "summary": "Refresh an expired access token",
        "operationId": "refreshSession",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["refreshToken"], "properties": { "refreshToken": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Refreshed session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSession" } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/auth/workspace": {
      "get": {
        "tags": ["Authentication"],
        "summary": "Read the current account, plan, and usage",
        "operationId": "getWorkspace",
        "security": [{}, { "bearerAuth": [] }],
        "responses": { "200": { "description": "Workspace or guest status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/billing/checkout": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Create an authorized Pro checkout URL",
        "description": "Ask the user to approve the exact cadence before calling. This returns a secure checkout URL and does not charge a wallet by itself.",
        "operationId": "startProCheckout",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["cadence"], "properties": { "cadence": { "type": "string", "enum": ["monthly", "annual"] } }, "additionalProperties": false } } } },
        "responses": { "200": { "description": "Secure Stripe checkout URL", "content": { "application/json": { "schema": { "type": "object", "required": ["url", "cadence"], "properties": { "url": { "type": "string", "format": "uri" }, "cadence": { "type": "string" }, "sessionId": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/skills/finder": {
      "get": {
        "tags": ["Skills"],
        "summary": "Find skills for a task",
        "operationId": "findSkills",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }
        ],
        "responses": { "200": { "description": "Matching skills", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/skills/{skillId}": {
      "get": {
        "tags": ["Skills"],
        "summary": "Retrieve one skill",
        "operationId": "getSkill",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SkillId" }],
        "responses": { "200": { "description": "Skill instructions and metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/skills/{skillId}/mcp-tool": {
      "get": {
        "tags": ["Skills"],
        "summary": "Retrieve the MCP tool definition for one skill",
        "operationId": "getSkillMcpTool",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SkillId" }],
        "responses": { "200": { "description": "MCP-compatible tool definition", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/sessions": {
      "get": {
        "tags": ["Capture"],
        "summary": "List workflow-capture sessions",
        "operationId": "listSessions",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }],
        "responses": { "200": { "description": "Capture sessions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      },
      "post": {
        "tags": ["Capture"],
        "summary": "Create a workflow-capture session",
        "operationId": "createSession",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string" }, "intent": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Created capture session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/sessions/{sessionId}/events": {
      "get": {
        "tags": ["Capture"],
        "summary": "List captured events",
        "operationId": "listSessionEvents",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": { "200": { "description": "Captured events", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      },
      "post": {
        "tags": ["Capture"],
        "summary": "Append events to a capture session",
        "operationId": "appendSessionEvents",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["events"], "properties": { "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } },
        "responses": { "200": { "description": "Events accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/sessions/{sessionId}/complete": {
      "post": {
        "tags": ["Capture"],
        "summary": "Finish a capture session",
        "operationId": "completeSession",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": { "200": { "description": "Completed session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/packages/compile": {
      "post": {
        "tags": ["Capture"],
        "summary": "Turn a completed capture into a structured workflow package",
        "operationId": "compilePackage",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sessionId"], "properties": { "sessionId": { "type": "string", "format": "uuid" } } } } } },
        "responses": { "200": { "description": "Compiled workflow package", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/goals": {
      "get": {
        "tags": ["Goals"],
        "summary": "List agent goals",
        "operationId": "listGoals",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Agent goals", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" } }
      },
      "post": {
        "tags": ["Goals"],
        "summary": "Start an agent goal",
        "description": "This action can consume plan usage. Keep visibility private unless the user explicitly requests publishing.",
        "operationId": "createGoal",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["prompt"], "properties": { "prompt": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "visibility": { "type": "string", "enum": ["private", "team", "public"], "default": "private" } } } } } },
        "responses": { "201": { "description": "Started goal and run", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } },
    "parameters": {
      "SkillId": { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "SessionId": { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
    },
    "responses": {
      "Error": { "description": "OWOJI API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }
    },
    "schemas": {
      "Health": { "type": "object", "required": ["status", "service"], "properties": { "status": { "type": "string", "const": "ok" }, "service": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "visibility": { "type": "string" } } },
      "SignInRequest": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "additionalProperties": false },
      "AuthSession": { "type": "object", "required": ["accessToken"], "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer" }, "user": { "type": "object", "additionalProperties": true }, "workspace": { "type": "object", "additionalProperties": true } } },
      "ErrorEnvelope": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } }
    }
  }
}