{
  "openapi": "3.0.3",
  "info": {
    "title": "Fluxopus API",
    "description": "REST API for the Fluxopus workflow automation tracker. All endpoints require a valid Supabase JWT and respect row-level security (users see only their own or their company's data).",
    "version": "1.0.0",
    "contact": {
      "email": "support@fluxopus.eu"
    }
  },
  "servers": [
    { "url": "https://fluxopus.eu/api", "description": "Production" }
  ],
  "security": [{ "BearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Supabase session JWT. Obtain via supabase.auth.getSession() or the Auth API."
      }
    },
    "schemas": {
      "Task": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "status": {
            "type": "string",
            "enum": ["identified", "in_progress", "automated", "measured"]
          },
          "frequency": {
            "type": "string",
            "enum": ["daily", "weekly", "monthly"],
            "nullable": true
          },
          "pain_level": { "type": "integer", "minimum": 1, "maximum": 5, "nullable": true },
          "automation_potential": { "type": "integer", "minimum": 1, "maximum": 5, "nullable": true },
          "time_before_minutes": { "type": "integer", "nullable": true },
          "time_after_minutes": { "type": "integer", "nullable": true },
          "visibility": { "type": "string", "enum": ["private", "company"] },
          "tools_used": { "type": "array", "items": { "type": "string" } },
          "user_id": { "type": "string", "format": "uuid" },
          "company_id": { "type": "string", "format": "uuid" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "TimeLog": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "task_id": { "type": "string", "format": "uuid" },
          "phase": { "type": "string", "enum": ["before", "after"] },
          "minutes": { "type": "integer" },
          "note": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Skill": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "prompt": { "type": "string" },
          "tools_available": { "type": "array", "items": { "type": "string" } },
          "visibility": { "type": "string", "enum": ["private", "company"] },
          "status": { "type": "string", "enum": ["idle", "running", "completed", "failed"] },
          "last_run_at": { "type": "string", "format": "date-time", "nullable": true },
          "execution_count": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "KnowledgeItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "content": { "type": "string" },
          "source": { "type": "string", "enum": ["manual", "skill_execution"] },
          "visibility": { "type": "string", "enum": ["private", "company"] },
          "user_id": { "type": "string", "format": "uuid" },
          "company_id": { "type": "string", "format": "uuid" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Connection": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "tool_slug": { "type": "string", "example": "google-sheets" },
          "scope": { "type": "string", "enum": ["user", "company"] },
          "status": { "type": "string", "enum": ["active", "expired", "revoked"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "color": { "type": "string", "nullable": true },
          "company_id": { "type": "string", "format": "uuid" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        },
        "required": ["error"]
      }
    }
  },
  "paths": {
    "/tasks": {
      "get": {
        "summary": "List tasks",
        "description": "Returns tasks visible to the authenticated user. Admins see company-wide tasks.",
        "operationId": "listTasks",
        "tags": ["Tasks"],
        "responses": {
          "200": {
            "description": "Array of tasks",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "summary": "Create a task",
        "operationId": "createTask",
        "tags": ["Tasks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title"],
                "properties": {
                  "title": { "type": "string" },
                  "description": { "type": "string" },
                  "status": { "type": "string", "enum": ["identified", "in_progress", "automated", "measured"], "default": "identified" },
                  "frequency": { "type": "string", "enum": ["daily", "weekly", "monthly"] },
                  "pain_level": { "type": "integer", "minimum": 1, "maximum": 5 },
                  "automation_potential": { "type": "integer", "minimum": 1, "maximum": 5 },
                  "time_before_minutes": { "type": "integer" },
                  "time_after_minutes": { "type": "integer" },
                  "visibility": { "type": "string", "enum": ["private", "company"], "default": "private" },
                  "tools_used": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/tasks/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "get": {
        "summary": "Get a task",
        "operationId": "getTask",
        "tags": ["Tasks"],
        "responses": {
          "200": { "description": "Task object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "patch": {
        "summary": "Update a task",
        "operationId": "updateTask",
        "tags": ["Tasks"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }
        },
        "responses": {
          "200": { "description": "Updated task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "delete": {
        "summary": "Delete a task",
        "operationId": "deleteTask",
        "tags": ["Tasks"],
        "responses": {
          "200": { "description": "Success" },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/tasks/{id}/time-logs": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "get": {
        "summary": "List time logs for a task",
        "operationId": "listTimeLogs",
        "tags": ["Tasks"],
        "responses": {
          "200": { "description": "Array of time logs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimeLog" } } } } }
        }
      },
      "post": {
        "summary": "Add a time log entry",
        "operationId": "createTimeLog",
        "tags": ["Tasks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["phase", "minutes"],
                "properties": {
                  "phase": { "type": "string", "enum": ["before", "after"] },
                  "minutes": { "type": "integer" },
                  "note": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created time log", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeLog" } } } }
        }
      }
    },
    "/skills": {
      "get": {
        "summary": "List skills",
        "operationId": "listSkills",
        "tags": ["Skills"],
        "responses": {
          "200": { "description": "Array of skills", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } } } }
        }
      },
      "post": {
        "summary": "Create a skill",
        "operationId": "createSkill",
        "tags": ["Skills"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "prompt"],
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "prompt": { "type": "string" },
                  "tools_available": { "type": "array", "items": { "type": "string" } },
                  "visibility": { "type": "string", "enum": ["private", "company"], "default": "private" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }
        }
      }
    },
    "/skills/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "get": {
        "summary": "Get a skill",
        "operationId": "getSkill",
        "tags": ["Skills"],
        "responses": {
          "200": { "description": "Skill object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }
        }
      },
      "patch": {
        "summary": "Update a skill",
        "operationId": "updateSkill",
        "tags": ["Skills"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } }
        },
        "responses": {
          "200": { "description": "Updated skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } } }
        }
      },
      "delete": {
        "summary": "Delete a skill",
        "operationId": "deleteSkill",
        "tags": ["Skills"],
        "responses": { "200": { "description": "Success" } }
      }
    },
    "/skills/{id}/run": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "post": {
        "summary": "Execute a skill",
        "description": "Runs the skill agent. Response is streamed as server-sent events.",
        "operationId": "runSkill",
        "tags": ["Skills"],
        "responses": {
          "200": { "description": "Streamed execution output (text/event-stream)" },
          "402": { "description": "Token budget exceeded or free plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/skills/{id}/versions": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "get": {
        "summary": "List skill version history",
        "operationId": "listSkillVersions",
        "tags": ["Skills"],
        "responses": {
          "200": { "description": "Array of version snapshots" }
        }
      }
    },
    "/knowledge": {
      "get": {
        "summary": "List knowledge items",
        "operationId": "listKnowledge",
        "tags": ["Knowledge"],
        "parameters": [
          { "name": "q", "in": "query", "description": "Semantic search query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Array of knowledge items", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeItem" } } } } }
        }
      },
      "post": {
        "summary": "Create a knowledge item",
        "operationId": "createKnowledge",
        "tags": ["Knowledge"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "content"],
                "properties": {
                  "title": { "type": "string" },
                  "content": { "type": "string" },
                  "visibility": { "type": "string", "enum": ["private", "company"], "default": "private" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeItem" } } } }
        }
      }
    },
    "/knowledge/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "get": {
        "summary": "Get a knowledge item",
        "operationId": "getKnowledge",
        "tags": ["Knowledge"],
        "responses": {
          "200": { "description": "Knowledge item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeItem" } } } }
        }
      },
      "patch": {
        "summary": "Update a knowledge item",
        "operationId": "updateKnowledge",
        "tags": ["Knowledge"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeItem" } } }
        },
        "responses": {
          "200": { "description": "Updated item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeItem" } } } }
        }
      },
      "delete": {
        "summary": "Delete a knowledge item",
        "operationId": "deleteKnowledge",
        "tags": ["Knowledge"],
        "responses": { "200": { "description": "Success" } }
      }
    },
    "/connections": {
      "get": {
        "summary": "List active connections",
        "operationId": "listConnections",
        "tags": ["Connections"],
        "responses": {
          "200": { "description": "Array of connections", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } }
        }
      }
    },
    "/connections/authorize/{provider}": {
      "parameters": [{ "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "example": "google" }],
      "get": {
        "summary": "Start OAuth flow",
        "description": "Redirects to the provider's OAuth consent screen. Not called directly — use the Connect button in the UI.",
        "operationId": "authorizeConnection",
        "tags": ["Connections"],
        "responses": {
          "302": { "description": "Redirect to OAuth provider" }
        }
      }
    },
    "/connections/status/{provider}": {
      "parameters": [{ "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "summary": "Check connection status",
        "operationId": "connectionStatus",
        "tags": ["Connections"],
        "responses": {
          "200": { "description": "Connection status", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" } } } } } }
        }
      }
    },
    "/connections/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "delete": {
        "summary": "Disconnect a tool",
        "operationId": "deleteConnection",
        "tags": ["Connections"],
        "responses": { "200": { "description": "Success" } }
      }
    },
    "/tags": {
      "get": {
        "summary": "List company tags",
        "operationId": "listTags",
        "tags": ["Tags"],
        "responses": {
          "200": { "description": "Array of tags", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } }
        }
      },
      "post": {
        "summary": "Create a tag",
        "operationId": "createTag",
        "tags": ["Tags"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string" },
                  "color": { "type": "string", "description": "Hex color string, e.g. #3b82f6" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }
        }
      }
    },
    "/tags/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "patch": {
        "summary": "Update a tag",
        "operationId": "updateTag",
        "tags": ["Tags"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }
        },
        "responses": {
          "200": { "description": "Updated tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }
        }
      },
      "delete": {
        "summary": "Delete a tag",
        "operationId": "deleteTag",
        "tags": ["Tags"],
        "responses": { "200": { "description": "Success" } }
      }
    },
    "/tags/entity": {
      "get": {
        "summary": "Get tags for an entity",
        "operationId": "getEntityTags",
        "tags": ["Tags"],
        "parameters": [
          { "name": "entityType", "in": "query", "required": true, "schema": { "type": "string", "enum": ["task", "skill", "knowledge_item"] } },
          { "name": "entityId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": { "description": "Array of tags", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } }
        }
      },
      "post": {
        "summary": "Assign tags to an entity",
        "operationId": "setEntityTags",
        "tags": ["Tags"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entityType", "entityId", "tagIds"],
                "properties": {
                  "entityType": { "type": "string", "enum": ["task", "skill", "knowledge_item"] },
                  "entityId": { "type": "string", "format": "uuid" },
                  "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}